PureBoot Getting Started Guide

This guide aims to document how to use PureBoot once it is set up on a machine such as is the case with the PureBoot Bundle, which configures PureBoot and a Librem Key at the Purism fulfillment center. In particular this guide documents how to use the Heads tamper-evident boot software with a Librem Key with default settings like those that are set during an OEM Factory Reset. For more technical documentation on how PureBoot or Heads works or how to build it or install it yourself, see the more in-depth documentation in the Heads User Manual.

PureBoot 101

Download Full Blog

LED Blinking

The Librem Key has a green and red LED. The green LED is only used at the beginning of the PureBoot process to prove the firmware hasn’t been tampered with. In that case the green LED will provide blink steadily a number of times and stop.

The red LED is not only used to warn about firmware tampering, but is also used to show activity whenever the Librem Key is accessed. For instance when you boot the system with a Librem Key inserted, the red LED will light up briefly as PureBoot detects the device. Also whenever you use the Librem Key to encrypt/decrypt/sign something, the red LED will light up while the GPG function is running on the device.

So how do you tell activity from a warning? And how do you detect tampering if you are red/green color blind? When the red LED is warning you of tampering, it will do so with a steady blinking pattern and will do so indefinitely until you unplug it from the computer. The green LED will blink steadily a limited number of times and then stop after a few seconds. When the red LED is used to show activity it lights up irregularly.

First Boot

Summary: Insert Librem Key, power on, confirm Librem Key LED blinks green, press enter, and boot!

Before you turn on the laptop for the first time, be sure that the Librem Key is inserted. While the Librem Key isn’t strictly required to boot your system, without it PureBoot can’t prove that the boot firmware has not been tampered with. PureBoot will show a warning at boot if the Librem Key isn’t inserted. If you do get this warning, you can insert the Librem Key at this point and hit enter, or otherwise you can hit enter to ignore the warning and proceed to the main menu.

Once you see the main menu, look at your Librem Key to confirm that the green LED is flashing–this proves that your PureBoot firmware hasn’t been tampered with. If the red LED is flashing on the Librem Key, this means that your boot firmware has been modified–either legitimately or maliciously. If this happens, skip down to the Warnings and Alerts section for more instructions on what to do.

The first and default option on the main menu is labeled “Default boot” and if you press enter, it will start the process of booting into your system. This is normally all you will need to do to boot your regular OS with PureBoot. Once you select “Default boot” the PureBoot firmware will scan all of the files in the /boot partition for any tampering and then boot into the OS. On the very first boot you should not expect to see any warnings or alerts about modified files.

First Reboot

Summary: PureOS modifies initrd at first boot, you will need to re-sign files in /boot the first time you reboot.

The first time you boot PureOS, it will launch a wizard where you can set your encryption passphrase, username and password, and other settings. This process (in particular changing the disk encryption passphrase) will modify the initrd file in /boot and, because that file changed, the first time you reboot your system after you select “Default boot” you will see a tampering alert. This alert will identify the modified initrd (and if you updated all of your packages before your first reboot it might also alert you to a modified kernel or grub.conf). Follow the defaults to re-sign the files in /boot using your Librem Key. If you get prompted to enter a PIN when re-signing files, the default is “123456” for the user PIN.

Changing Default Secrets

Summary: You should change the default passwords Purism sets for PureBoot and the Librem Key at the factory.

PureBoot uses a number of different passwords and Purism sets the same default passwords for each PureBoot Bundle:

  • Librem Key User PIN: 123456

  • Librem Key Admin PIN: 12345678

  • TPM Admin Password: 12345678

The Librem Key GPG user PIN is the main password you will use with PureBoot as it’s the PIN you use to re-sign files in /boot. Any time you update your system and it modifies the initrd, grub.conf or kernel files in /boot you will be prompted to enter this PIN to re-sign those files.

The Librem Key GPG admin PIN is used for administrative operations on your Librem Key, like changing the default GPG keys on the device, or changing the user PIN. The Librem Key admin PIN is also used whenever you need to reset the HOTP token in PureBoot–this is the secret shared between the TPM chip and your Librem Key that lets the Librem Key know when the firmware has been tampered with. This would happen any time you modify the PureBoot firmware itself including:

  • Changing internal settings

  • Adding new GPG keys to the PureBoot keyring

  • Flashing an updated PureBoot firmware

  • The TPM has been reset

To change the GPG user and admin PIN on your Librem Key, follow this guide in our Librem Key documentation.

Changing the TPM Admin password

The TPM Admin password is used less frequently but you might be prompted for this password if you were to flash a brand new PureBoot firmware and erase any existing settings, or when selecting a new default boot option. To change the TPM admin password you need to reset the TPM completely, which will erase any existing secrets, so you will end up configuring a new HOTP password for your Librem Key as well. To do this from the main PureBoot menu select Options → TPM/TOTP/HOTP Options → Reset the TPM and follow the prompts.

Changing GPG Keys

You may also want to replace the factory-provided GPG keys with keys you generate. To do so, 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.

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.

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 PureBoot 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.

Once you have a copy of the public key on a USB drive, reboot into PureBoot, insert the thumb drive, and then select Options → GPG Options → Replace GPG key(s) in the current ROM + reflash. This will detect any GPG public keys you have present on your thumb drive and present them to you so you can select the one to add. Once you select it, Heads will replace any existing GPG keys in the keyring with the key you selected.

Once you reflash and reboot, you will need to re-sign all of the files in /boot with your new key, so select Options → Update checksums and sign all files in /boot.

Other Booting Options

Summary: Select Options → Boot Options to see alternate boot options.

From the factory, PureBoot is configured to boot the first PureOS kernel option in grub.conf–when you select “Default boot” at the main menu this is the option that boots. If you would like to boot into a PureOS rescue mode or boot an alternate kernel, select Options → Boot Options → Show OS Boot menu. This will display all of the boot options available in your system’s grub.conf file. Note that when you select something from the alternate boot menu, you’ll have the option to replace your current default option with it.

PureBoot can also boot from a USB disk. Just insert your USB disk and select Options → Boot Options → USB boot.

Finally, PureBoot will never lock you out of your system, even in the event it detects tampering. If you attempt to boot your machine and PureBoot shows an alert, but you would like to boot it anyway, select Options → Boot Options → Ignore tampering and force a boot (Unsafe!) to continue booting.

Warnings and Alerts

Summary: If you see an alert, don’t panic! Follow the prompts to resolve it.

The normal operation of PureBoot is relatively hands-off, much like traditional GRUB systems–just turn on the computer, press enter, and your system boots. Behind the scenes, though, PureBoot is performing a number of different tests to detect tampering on the system. Routine tasks like updating the software on your system might potentially trigger a tampering warning so if you do see a warning or alert, don’t panic! Just read and follow the instructions on the screen. In this section we will cover some of the most likely alerts you will see, what they mean, and how to respond to them.

Librem Key is not Inserted

If you boot your system without your Librem Key inserted, you will get a warning. This gives you an opportunity to insert the Librem Key before pressing OK, so PureBoot can prove it hasn’t been tampered with. If you don’t have your Librem Key, you can just select “OK” to skip this warning and boot the system. Just realize that you are skipping the firmware tamper detection.

Librem Key Flashes Red

Note that if an attacker has modified the firmware, they can change the screen to make things appear normal. The value of the Librem Key is that while the screen might lie, the Librem Key won’t. If the Librem Key flashes red, it could indicate that someone has tampered with the firmware, or it could also be triggered by a number of other circumstances–all related to you making changes to PureBoot:

  • Changing internal PureBoot settings

  • Adding new GPG keys to the PureBoot keyring

  • Flashing an updated PureBoot firmware

  • The TPM has been reset

If you have not made any changes to PureBoot and your Librem Key is flashing red unexpectedly, it could indicate tampering. Otherwise if you have made some of the above changes, just follow the prompts on the screen to set a new TOTP/HOTP secret on your Librem Key.

Files in /boot have been modified

The most common alert you will likely see when using PureBoot occurs after you tell the system to boot. At that point PureBoot will scan all of the files in /boot to see if any have been modified before it boots into your OS. If any of the files it has previously signed have changed, PureBoot will show an alert that tells you which files have changed. Note that there are a number of routine tasks you will perform on your OS that will trigger this alert:

  • Updating system packages that refresh the initrd

  • Updating your kernel (which changes grub.conf)

  • Making custom changes to your GRUB configuration

PureOS uses a software update tool called Packagekit that reboots the system to install updates safely. If you get prompted that your system has updates to apply and you tell it to reboot to apply them, you then can test that PureBoot is still in a safe state before updates when it reboots. Then when it applies the updates and reboots again, if you see a PureBoot alert about modified files in /boot, you can be assured that it was caused by the software update.

Otherwise, if you have not updated or changed your system since the last boot, and you see this alert, this could indicate that someone has tampered with your kernel or other files in /boot.

OEM Factory Reset

If you would like to return PureBoot and your Librem Key to factory settings, you can do this from within PureBoot. The OEM Factory Reset menu will display warning to alert you to all of the changes it will make. Note that this option will erase any keys on your Librem Key as well as reset the TPM and generate new keys and default passwords for everything.

To perform an OEM Factory Reset, insert both your Librem Key and a USB disk so PureBoot can copy over the new corresponding GPG public key it generates. Then select Options → OEM Factory Reset and follow the prompts. The process will take some time as it needs to generate new GPG keys. Then once it completes you will be prompted to reboot the system. At that point you will get an alert that you will need to generate a new TOTP/HOTP secret (when prompted, the TPM admin PIN as well as the Librem Key admin PIN are “12345678”).

Updating PureBoot Firmware

From time to time we release new PureBoot firmware. You can update PureBoot firmware directly from PureBoot itself! First, get the latest version of the PureBoot firmware for your hardware, either directly from https://source.puri.sm/coreboot/releases (be sure to get the correct image for your hardware and gunzip it!) or by running our coreboot utility. In either case you will copy the .rom file to a USB disk, reboot into PureBoot, insert your USB disk and select Options → Flash/Update the BIOS → Flash the firmware with a new ROM, retain settings. Remember that whenever you update the firmware, you can expect to get an alert at the next boot to update your TOTP/HOTP secret.

Reverting to the non-PureBoot, coreboot BIOS

You can perform similar steps that you would use to update PureBoot firmware, to revert back to the default coreboot firmware we ship on our laptops by default. Just download the standard legacy SeaBIOS either from https://source.puri.sm/coreboot/releases or by running our coreboot utility. In either case you will copy the .rom file to a USB disk, reboot into PureBoot, insert your USB disk and select Options → Flash/Update the BIOS → Flash the firmware with a new ROM, erase settings. Note that in this case we tell PureBoot to erase settings not retain them, since we are flashing SeaBIOS over PureBoot.