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 an open Beta program and while this documentation will describe how to build, install, and use Heads on Librem hardware, it is still a complicated process intended for more technical users and involves manually flashing a BIOS. We have created a community Matrix channel for Heads users at #community-heads:talk.puri.sm.

Heads Beta Installation Instructions

Heads is technical software we consider in a Beta state and intended for more technical users. This documentation is for those who want to be part of the Purism Heads Beta testing program. Please make sure to read and understand the instructions before starting the installatino process.

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 at #community-heads:talk.puri.sm for troubleshooting

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

  • Use our utility to download or build a pre-built 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
  • Use our utility to download and flash a pre-built PureBoot firmware image for your Librem hardware
  • (Optionally) Build Heads for your Librem hardware and flash it manually
  • Perform initial Heads configuration

Download Coreboot

Before you install Heads, you should download the very latest version of coreboot for your system. This is important because this process will create a backup coreboot ROM 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. You can also use this same script to pull down the Heads PureBoot image later. Full documentation for the coreboot utility script can be found in the README at https://source.puri.sm/coreboot/utility, but here’s the TL;DR: simply open a terminal and run the following commands:

mkdir ~/updates
cd ~/updates
wget https://source.puri.sm/coreboot/utility/raw/master/coreboot_util.sh -O coreboot_util.sh
sudo bash ./coreboot_util.sh

When prompted, select the “Standard” firmware for your hardware. You will have the option to save time by pulling down a pre-built binary image of coreboot, or build one from source, depending on your preference. You can see screenshots of this process at https://puri.sm/coreboot. Once you have either downloaded the image or built coreboot, you can tell it to not flash the coreboot update now, so you can instead just copy the coreboot imagedirectory onto a USB thumb drive in case you need to revert back to them from within Heads:

cp *.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.

Now that Heads supports GPG version 2, it can support larger 4096 bit keys. Previous versions used GPG version 1 and were limited to 2048 bit keys.

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.

Download and Flash Heads Firmware for your Librem 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. You can use the same utility you used to download the coreboot ROM to download and flash a pre-built PureBoot firmware image that contains Heads. If you didn’t already download the coreboot utility in the above steps, you can do so now:

mkdir ~/updates cd ~/updates wget https://source.puri.sm/coreboot/utility/raw/master/coreboot_util.sh -O coreboot_util.sh sudo bash ./coreboot_util.sh

When prompted, select the “PureBoot” firmware for your hardware. The script will then download the firmware and if you have not yet flashed PureBoot Heads firmware to your laptop, you will be able to flash it directly from this script. Otherwise you will have to copy the updated firmware to a USB drive and flash from within Heads itself. The script will attempt to use your distribution’s flashrom if it can (the version in PureOS is new enough, but in other distributions it may not be) and otherwise it will download and compile flashrom from source.

Once you have completed this step, skip down to the Perform initial Heads configuration section of the document.

(Optional) Build Heads for your Librem hardware

Note: To avoid the risk of building Heads with incorrect options, we recommend using our pre-built binary ROM we provide in our coreboot utility script. We are leaving these steps in place for users who want to build Heads themselves from scratch.

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://source.puri.sm/coreboot/purism-heads.git

Heads will require a number of build dependencies for its own version of coreboot as well as additional dependencies for other packages it includes, so you will need to install those now:

sudo apt install git build-essential bison flex m4 zlib1g-dev gnat libpci-dev libusb-dev libusb-1.0-0-dev dmidecode bsdiff python2.7 pv libelf-dev pkg-config cmake

(Deprecated) Editing Boot Configuration

Note that the following configuration options are no longer necessary, as our Heads build has the ability to update this configuration within the Heads menu itself. You can still update the configuration here if you wish, so the following config is in the documention for your refrence. Otherwise skip ahead to the next section.

There are four main Librem board categories within Heads, one for the Librem 13v2/13v3, one for the Librem 15v3, one for Librem 13v4 and one for Librem 15v4. Under the boards/ directory you will see a librem13v2, librem13v4, librem15v3 and librem15v4 directory. Within each of these directories is a corresponding librem13v2.config, librem13v4.config, librem15v3.config or librem15v4.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. There is a blobs/librem_skl and blobs/librem_kbl directory that contains a get_blobs.sh script to pull down blobs. You will execute the script from a different directory depending on which version laptop you have.

For Librem 13v2/13v3 and Librem 15v3 owners:

cd blobs/librem_skl
./get_blobs.sh

For Librem 13v4 and Librem 15v4 owners:

cd blobs/librem_kbl
./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 13v4 laptops type:

make BOARD=librem13v4

For Librem 15v3 laptops type:

make BOARD=librem15v3

For Librem 15v4 laptops type:

make BOARD=librem15v4

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, build/librem13v4/coreboot.com, build/librem15v3/coreboot.rom or build/librem15v4/coreboot.com depending on your device.

Flash the compiled Heads ROM 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 executable installed on your system but note that if the flashrom is not greater than 1.0, you will need to build it yourself. The following commands assume the 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 flashrom -p internal:laptop=force_I_want_a_brick,ich_spi_mode=hwseq -w build/librem13v2/coreboot.rom

For the Librem 13v4 type:

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

For the Librem 15v3 type:

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

For the Librem 15v4 type:

sudo flashrom -p internal:laptop=force_I_want_a_brick,ich_spi_mode=hwseq -w build/librem15v4/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.

Update Heads Firmware for your Librem Hardware

To update your PureBoot firmware to the latest release of Heads, run the same utility script you used to download and flash Heads so you can pull down a copy of the pre-built image. Note that we advise users to flash Heads updates from within the trusted Heads environment itself.

Other Resources