These instructions are only for the Lenovo Thinkpad x230 and require physical access to the hardware. There are risks in installation that might brick your system and cause loss of data. You will need another computer to perform the flashing and building steps. If you want to experiment, consider Emulating Heads with qemu before installing it on your machine.
There are five major steps:
- Flashing the boot ROM
- Taking ownership of the TPM
- Installing Qubes
- Sealing disk encryption keys
- Signing Qubes installation
Unplug the system and remove the battery while you’re disassebling the machine! You’ll need to remove the palm rest to get access to the SPI flash chips, which will require removing the keyboard. There are seven screws marked with keyboard and palm rest symbols.
The keyboard tilts up on a ribbon cable. You can keep the cable installed, unless you want to swap the keyboard for the nice x220 model.
The palm rest trackpad ribbon cable needs to be disconnected. Flip up the retainer and pull the cable out. It shouldn’t require much force. Once the palmrest is removed you can replace the keyboard screws and operate the machine without the palm rest. Since the thinkpad has the trackpoint, even mouse applications will still work fine.
There are two SPI flash chips hiding under the black plastic, labelled “SPI1” and “SPI2”. The top one is 4MB and contains the BIOS and reset vector. The bottom one is 8MB and has the Intel Management Engine (ME) firmware, plus the flash descriptor.
Using a chip clip and a SPI programmer, dump the existing ROMs to files. Dump them again and compare the different dumps to be sure that were no errors. Maybe dump them both a third time, just to be safe.
Ok, now comes the time to write the 4MB
x230.coreboot.bin file to SPI2 chip. With my programmer and minicom, I hit i to verify that the flash chip signature is correctly read a few times, and then send
u0 400000↵ to initiate the upload. I then drop to a shell with Control-A J and finally send the file with
pv x230.rom > /dev/ttyACM0↵. A minute later, I resume minicom and hit i again to check that the chip is still responding.
Move the clip to the SPI1 chip and flash the 8 MB
x230.me.bin (TODO: document how to produce this with me cleaner -> Clean the ME firmware). This time you’ll send the command
u0 800000↵. This will wipe out the official Intel firmware, leaving only a stub of it to bring up the Sandybridge CPU before shutting down the ME. As far as I can tell there are no ill effects other than an inability to power off the machine without using the power switch.
Finally, remove the programmer, connect the power supply and try to reboot.
If all goes well, you should see the keyboard LED flash, and within a second the Heads splash screen appear. It currently drops you immediately into the shell, since the boot script portion has not yet been implemented. If it doesn’t work, well, sorry about that. Please let me know what the symptoms are or what happened during the flashing.
Congratulations! You now have a Coreboot + Heads Linux machine. Adding your own signing key, installing Qubes and configuring tpmtotp are the next steps and need to be written.
Adding your PGP key
Heads uses your own GPG key to sign updates and as a result it needs the
key stored in the
initrd.cpio file that is built as part of the ROM image.
In the future (issue #182)
it might be possible to install your own key from inside the recovery
shell; this would be preferable for many reasons.
Insert your Yubikey into the build machine and in the
heads build directory,
clean out the old files, then invoke GPG’s the “Card Edit” function with
it targetting the local directory:
rm ./initrd/.gnupg/* gpg --card-edit --homedir ./initrd/.gnupg
Go into “Admin” mode and generate a new key inside the Yubikey:
Since this key can be replaced by replacing the ROM, it is not necessary
to make a backup unless you want to.
This will prompt you for the admin pin (
12345678 by default) and then
the existing pin (
123456). Follow the other prompts and eventually
you should have a key in
Configuring the TPM
There aren’t very many good details on how to setup TPMs, so this section could use some work.
If you’ve acquired the machine from elsewhere, you’ll need to establish physical presence, perform a force clear and take ownership with your own password. Should the storage root key (SRK) be set to something other than the well-known password?
There is something weird with enabling, presence and disabling. Sometimes reboot fixes the state.
Once you own the TPM and have the final version of the
x230.rom flashed, run
seal-totp to generate a random secret, seal it with the current TPM PCR values and store the sealed value in the TPM’s NVRAM. This will generate a QR code that you can scan with your google authenticator application and use to validate that the boot block, rom stage and Linux payload are un-altered.
On the next boot, or if you run
unseal-totp, the script will extract the sealed blob from the NVRAM and the TPM will validate that the PCR values are as expected before it unseals it. If this works, the current TOTP will be computed and you can compare this one-time-password against the value that your phone generates.
This does not eliminate all firmware attacks (such as evil maid ones that replace the SPI flash chip), but when combined with the WP# pin and BP bits should eliminate a software only attack.
Boot into the recovery shell (hit ‘r’ at the prompt before the normal startup script tries to run) and plug the USB stick with the R3.2 install media into one of the USB3 ports (on the left side of the x230) and run the helper script to start the Qubes installer:
If that completes with no errors with will launch the Xen hypervisor from the x230’s ROM image and start the Qube’s installer. The first few seconds are run with an archaic video mode, so things appear a little wrid, but once the dom0 kernel initializes the graphics it should look right.
My recommended partitioning scheme is to use LVM and to allocate 1G for
/boot since it will hold the dm-verity hashes, 48G for
/, 8G for swap and the rest for
/home. Don’t adjust the filesystem labels or the volume group; this will be used by the startup script.
The disk encrypt password that you enter here will be used as the “recovery password” later. It should be a long value since you won’t have to enter it very often; only when upgrading the Heads firmware or if there is a need to recover the disk on an external machine. You will need it again shortly, so don’t lose it yet.
Once Qubes has finished installing, you’ll need to reboot into the Heads recovery shell. The first reboot will fail with errors about “
/boot/boot.hashes does not exist”, since it doesn’t.. The first step is to copy the Heads Xen to the
/boot drive, sign them and let Qubes finish its initialization.
mount -o rw,remount /boot cp /bin/xen.gz /boot/xen-4.6.4-heads.gz mount -o ro,remount /boot qubes-boot /boot/xen-4.6.4-heads.gz /boot/vm... /boot/initramfs...
You will need to input the disk recovery key here (almost for the last time),
and this should start the final stage of the Qubes installer. Under
you should select Create USB qube holding all USB controllers` so that they are protected from outside devices. This step takes a little
while as the templates are configured…
Eventually this will be done and you can click “Finish”, then Qubes will give you a login screen with your login password.
Now we need to make a small change to have Qubes’ initramfs correctly find the TPM encrypted keys. Open a dom0 terminal (click on the Q in the upper left and select
Terminal Emulator). In this shell run this perl command and rebuild the initrd with dracut (takes several seconds):
TODO: how to force all of crypttab to be emitted?
sudo perl -pi -e 's: none: /secret.key' /etc/crypttab sudo dracut --force
Reboot by selecting “Logout” and “Reboot” and you should be back to the
Heads recovery shell with the
boot.hashes error. Insert your Yubikey and run
(hit tab to autocomplete the file names):
qubes-update /boot/xen-4.6.4-heads.gz /boot/vmlinux... /boot/initramfs...
This should prompt you for the TPM owner password to create the new
counter (only the first time), then for your GPG card’s password.
It will output
with the signed hashes of the executables.
Lastly you’ll need to seal the disk encryption keys with a disk unlock key
that you will enter everytime. Run
seal-key and it will prompt you for
the disk recovery key (the long one you entered above), a disk unlock
key that you will enter on every boot, and on your first run also the
TPM owner password to create the NVRAM space.
Installing extra software
dom0 probably has updates available. You’ll want to install them before switching
/ to read-only and signing the hashes:
You’ll need the dm-verity tools to enable hashing
sudo qubes-dom0-update veritysetup
powertop is useful for debugging power drain issues. In dom0 run:
sudo qubes-dom0-update powertop
You might want to make the middle button into a scroll wheel. Add this to
Section "InputClass" Identifier "Trackpoint Wheel Emulation" MatchProduct "TPPS/2 IBM TrackPoint|DualPoint Stick|Synaptics Inc. Composite TouchPad / TrackPoint|ThinkPad USB Keyboard with TrackPoint|USB Trackpoint pointing device|Composite TouchPad / TrackPoint" MatchDevicePath "/dev/input/event*" Option "EmulateWheel" "true" Option "EmulateWheelButton" "2" Option "Emulate3Buttons" "false" Option "XAxisMapping" "6 7" Option "YAxisMapping" "4 5" EndSection
You’ll probably want to enable fan control, as described on ThinkWiki.
Disabling the ethernet might make sense to save power
There are some changes to Qubes’ files that have to be made first. Patches were posted to the qubes-devel list, although they need to be updated.
TODO: write a script to apply all of these fixes
Hashing the / partition and setting up dm-verity
Signing /boot — TPM Disk encryption keys — The keys are currently derived only from the user passphrase, which is expanded via the LUKS expansion algorithm to increase the time to brute force it. For extra protection it is possible to store the keys in the TPM so that they will only be released if the PCRs match.
This section is an early draft
There are two tools in the Heads ROM image for working with the TPM keys.
seal-key will generate a new key, seal it with the current PCRs and add a TPM passphrase, then store it into the TPM NVRAM.
unseal-key will extract it from the NVRAM and request the user passphrase to decrypt/unseal it. If the PCRs do not match, the TPM will reject the attempt (and hopefully dump keys after too many tries?).
To setup the drive encryption, generate and seal a new key. Then unseal it to create
/tmp/secret.key in the initial ramdisk. Delete the old keys from the root, home and swap partitions (can this use disk labels?):
cryptsetup luksKillSlot /dev/sda2 1 cryptsetup luksKillSlot /dev/sda3 1 cryptsetup luksKillSlot /dev/sda5 1
Then add the (now cleartext) key to each partition:
cryptsetup luksAddKey /dev/sda2 /tmp/secret.key cryptsetup luksAddKey /dev/sda3 /tmp/secret.key cryptsetup luksAddKey /dev/sda5 /tmp/secret.key
NOTE: should the new LUKS headers be measured and the key re-sealed with those parameters? This is what the Qubes AEM setup uses and is probably a good idea (although we’ve already attested to the state of the firmware).
This is where things get messy right now. The key file can not persist on disk anywhere, since it would allow an adversary to decrypt the drive. Instead it is necessary to unseal/decrypt the key from the TPM and then bundle the key file into a RAM copy of Qubes’ dom0 initrd on each boot. The initramfs format allows concatenated cpio files, so it is easy for the Heads firmware to inject files into the Qubes startup script.
Soldering jumpers on WP# pins, setting BP bits, epoxy blobs.