About Heads

Heads is secure BIOS replacement that provides tamper-evident features to detect when the BIOS or important boot files have been modified. The official project page can be found at the official Heads GitHub page and we base our Heads BIOS off of this code. On Purism laptops Heads is built as an executable on top of the same coreboot BIOS that we have used in the past but instead of coreboot running SeaBIOS to detect and boot into your devices, coreboot runs Heads instead.

Current Status

Currently Heads is available as part of a closed Beta program and while this documentation will describe how to build, install, and use Heads on Librem hardware, it is still a risky and complicated process intended for very technical users and involves compiling Beta software and manually flashing a BIOS. Note that Heads on Librem hardware is not yet an officially-supported product so keep that in mind if you want to test it on your own hardware outside of our closed Beta. If you want to join the closed Beta, email our CSO Kyle Rankin.

Heads Beta Installation Instructions

This documentation is intended for members of the Purism Heads Beta testing program. If you are not part of the beta program follow these instructions at your own risk.

Requirements

Testing Heads will require the following:

  • A USB thumb drive to store coreboot images and your GPG public key
  • A Librem Key
  • A Librem Laptop with a TPM chip running PureOS (sorry Qubes users, the dom0 flashrom is too old)
  • A spare computer/phone you can use to communicate in the Heads community Matrix channel for troubleshooting

The general process for testing Heads will involve the following steps:

  • Build the latest Purism coreboot image for your hardware and back it up to a thumb drive
  • Generate GPG keys to use with Heads
  • Copy the GPG subkeys to your Librem Key
  • Copy the GPG public key to your thumb drive
  • Build Heads for your Librem hardware
  • Flash Heads to your hardware
  • Perform initial Heads configuration

Build Coreboot

Before you build and install Heads, you should build the very latest version of coreboot for your system. This is important both because this process will create a backup coreboot ROM of both your current factory BIOS and the most recent coreboot BIOS for you to copy to a USB thumb drive. That way you will be able to revert back from Heads to your factory BIOS if you wish. The second reason this is important is that in the process of building coreboot you will pull in most of the dependencies you will need to build Heads. The third reason is that this process will build a recent version of flashrom, which you will use to flash Heads on your system later.

One of the first rules of documentation is that if the same documentation exists in two locations, one of the locations is out of date, so instead of making a copy of the coreboot install docs here, visit https://puri.sm/coreboot/ and follow the instructions for “Building coreboot on your own machine” to copy down the build script and build and install coreboot.

Once you have built coreboot, copy the coreboot.rom and coreboot-orig.rom files from the base of your building-coreboot directory onto a USB thumb drive in case you need to revert back to them from within Heads:

cp coreboot*.rom /media/<username>/<drivename>/

Generate GPG keys to use with Heads

Heads will need a set of GPG keys it can use to sign files within the /boot directory. You will need to put a copy of these GPG subkeys on your Librem Key and copy the corresponding public key to a USB thumb drive so you can import it into the Heads GPG keyring later. If you don’t already have GPG keys you want to reuse, you will need to generate one now. Follow the steps in our Librem Key User Manual to set up your Librem Key and generate GPG keys and subkeys for use on the Librem Key.

Note that currently Heads only has GPG version 1, which means it cannot support keys larger than 2048 bit so when you generate subkeys, you will need to make them 2048 bit or less.

Copy the GPG subkeys to your Librem Key

Whether you are reusing an existing set of subkeys or have generated them now just for Heads, follow the steps in our Librem Key User Manual, specifically the “Move GPG Subkeys Over to The Librem Key” section to copy the subkeys over to your Librem Key.

Copy the GPG public key to your thumb drive

Finally, insert a thumb drive and copy your ascii-armored GPG public key to it. Be sure that the file ends in .asc so that Heads will be able to detect it. In case you haven’t created a GPG public key file yet, run:

gpg --armor --output pubkey.asc --export <youremail@yourdomain.com>

Then copy the pubkey.asc file to a USB thumb drive.

Build Heads for your Librem hardware

The first step to build Heads for your Librem hardware is to pull down the full source code repository for it. For the purposes of this beta we have created a special branch that contains pull requests that have not yet been merged into the Heads master repo. So first clone the following repository:

git clone --branch purism_beta https://github.com/kylerankin/heads.git

Heads will require additional dependencies beyond what you needed to build coreboot, so you will need to install those now:

sudo apt install libelf-dev pkg-config cmake

There are two main Librem board categories within Heads, one for the Librem 13v2/13v3 and one for the Librem 15v3. Under the boards/ directory you will see a librem13v2 and librem15v3 directory. Within each of these directories is a corresponding librem13v2.config or librem15v3.config file. Open the config file that corresponds to your laptop and inspect the following configuration values:

export CONFIG_BOOT_DEV="/dev/sda1"
export CONFIG_USB_BOOT_DEV="/dev/sdb1"

These options hard-code which devices Heads should use for your /boot partition and for your USB boot device, respectively. If your Librem laptop just has a SATA hard drive in it, you should be able to leave these values as is.

If your Librem laptop has an NVMe drive in it instead, you should change the above values to:

export CONFIG_BOOT_DEV="/dev/nvme0n1p1"
export CONFIG_USB_BOOT_DEV="/dev/sda1"

If your Librem laptop has both a SATA drive and an NVMe drive in it, and you intend on booting from the SATA drive you can leave these configuration values alone and stick to the default values. On the other hand if you want to boot from the NVMe drive and you have a SATA drive installed, you will need to update the USB boot device as it will end up showing up on /dev/sdb1:

export CONFIG_BOOT_DEV="/dev/nvme0n1p1"
export CONFIG_USB_BOOT_DEV="/dev/sdb1"

Add Binary Blobs for Coreboot

Coreboot on Librem laptops unfortunately still requires a few binary blobs to run, so you will need to copy those down before you build Heads. Within the blobs/librem_skl directory is a get_blobs.sh script that you can execute to get the blobs:

cd blobs/librem_skl
./get_blobs.sh

Once the script completes, you can cd back to the main Heads directory and prepare to build.

Make the Heads ROM image

To make the Heads ROM image, from the base of the Heads code directory, run make followed by an environment variable that tells Heads which board to use. For Librem 13v2/13v3 laptops type:

make BOARD=librem13v2

For Librem 15v3 laptops type:

make BOARD=librem15v3

The first time you build Heads it will take quite a long time (hours) to complete the build process as it will need to pull down and compile the entire cross-compile toolchain. If for some reason the build process errors out, make a note of which module it was attempting to build and then go to the logs/ directory and inspect the logs for that particular module. More often than not a build fails because you are missing a development library on your system.

Once Heads completes the build process, you will find the corresponding ROM file at build/librem13v2/coreboot.rom or build/librem15v3/coreboot.rom depending on your device.

Flash Heads to your hardware

Before you flash Heads over the top of your existing coreboot BIOS, confirm that you have a USB thumb drive that contains your backup coreboot BIOS and your GPG public key. Then, use the flashrom you built initially from the building-coreboot directory to flash this new image. Assuming both the building-coreboot and heads directories are sitting in your home directory and you are still inside the main heads/ directory, the command for Librem 13v2/13v3 would look like:

sudo ../building-coreboot/coreboot/flashrom/flashrom -p internal:laptop=force_I_want_a_brick,ich_spi_mode=hwseq -w build/librem13v2/coreboot.rom

For the Librem 15v3 type:

sudo ../building-coreboot/coreboot/flashrom/flashrom -p internal:laptop=force_I_want_a_brick,ich_spi_mode=hwseq -w build/librem15v3/coreboot.rom

Once flashrom completes you are ready to reboot into Heads.

Perform initial Heads configuration

TODO: Provide screen captures with screenshots of the setup screen.

The first time Heads boots, it will require a bit of initial setup. It should detect that its keyring is empty and prompt you immediately to add a GPG public key. Follow the prompts and insert your USB thumb drive containing your GPG public key. Heads will reflash your BIOS with an updated version that contains this new keyring.

When Heads reboots, the next warning you will get will be about errors from the TPM. These are the same kinds of errors that you would get if someone modified the BIOS maliciously, but in this case you have not yet initialized the TPM so follow the prompts to reset the TPM. In the subsequent menus you will be able to choose a new admin password for the TPM (be sure to write it down or add it to a password manager, otherwise you can always reset the TPM later and set a new password). Once you set up the TPM it will then display a QR code on the screen. Since you are using a Librem Key to verify Heads, this step is optional and you can skip ahead to configure the Librem Key. You will be prompted to enter your Librem Key admin password, which defaults to 12345678 but see the Librem Key documentation for instructions on how to change it. Once you have finished setting up the Librem Key Heads will reboot again.

Finally at this point you should see the default Heads menu. Select Default Boot even though you haven’t configured that yet–Heads will detect it hasn’t been configured and will walk you through the process of signing all of the files in /boot and selecting a default boot option. Follow the prompts and when prompted to insert your GPG key, insert the Librem Key containing your private GPG subkeys and then enter your user PIN (which defaults to 123456) to sign all of the files.

Note that during the process of setting up the default boot option, Heads will ask you whether you want to store your LUKS password in the TPM. This is not currently a supported option so stick to the default answer, no, when prompted. You should then boot into your OS.

Other Resources