Getting Started¶
This guide documents how to use PureBoot with the PureBoot Bundle. Bundled devices are configured with a Librem Key at the Purism fulfillment center.
To add a Librem Key to a device shipped with PureBoot Basic, disable Basic mode, then perform an OEM Reset.
To switch from coreboot/SeaBIOS, use the coreboot utility to install PureBoot, then perform an OEM Reset.
For more technical documentation on how PureBoot or Heads works, including how to build and install it yourself, see the Heads documentation.
PureBoot 101
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 blink steadily a few 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. When 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¶
Insert Librem Key, power on, confirm Librem Key LED blinks green, press enter, and boot!
Before you turn on the device 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 press Enter, or you can press Enter to ignore the warning and proceed to the main menu.
While Pureboot starts, 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, refer to this section for more instructions.
On the very first boot, you should not see any warnings or alerts about modified files.
PureBoot will boot your OS automatically by default if the boot files have not been modified. To enter the main menu instead, press a key when PureBoot says it will boot automatically in a few seconds. Automatic boot can be changed from Configuration Settings.
First Reboot¶
PureOS modifies the boot files during the first boot. You will need to re-sign boot files 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. The boot files are changed to apply these settings, so the first time you reboot, you will see a tampering alert. This alert will show the modified files. Follow the defaults to re-sign the boot files using your Librem Key. If you are prompted to enter a PIN when re-signing files, the default is “123456” for the user PIN.
Changing Default Secrets¶
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 Owner Password: 12345678
The Librem Key GPG user PIN is the main password you will use with PureBoot. It is used to re-sign the boot files. Any time you update your system and it modifies the boot files, 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 happens any time you modify the PureBoot firmware itself including:
Changing PureBoot settings
Adding new GPG keys to the PureBoot keyring
Flashing an updated PureBoot firmware
Resetting the TPM
To change the GPG user and admin PIN on your Librem Key, follow this guide in our Librem Key documentation.
Changing the TPM Owner password¶
The TPM Owner password is used less frequently. 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 owner password, you need to reset the TPM, which will erase any existing secrets. This means you will configure 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 these steps 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 PureBoot, follow the steps in our Librem Key guide 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 and 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.
Select Options → Update checksums and sign all files in /boot.
Other Booting Options¶
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 boot from a USB disk. Just insert your USB disk and select Options → Boot Options → USB boot.
PureBoot can also decrypt LUKS using a Librem Key. For more information, see the Librem Key documentation.
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¶
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. However, note that you are skipping the firmware tamper detection.
Librem Key Flashes Red¶
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 caused by making changes to PureBoot:
Changing internal PureBoot settings
Adding new GPG keys to the PureBoot keyring
Flashing an updated PureBoot firmware
Resetting the TPM
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.
Boot files 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 boot files 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 reboots the system to install updates safely. If you reboot to apply updates, you 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 boot files, 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 boot files.
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 all of the changes it will make.
Warning
This option will erase any keys on your Librem Key, reset the TPM, and generate new keys.
If you choose to use the default settings, default passwords will be set as well.
To perform an OEM Factory Reset, insert your Librem Key. Now select Options → OEM Factory Reset and follow the prompts. The process will take a few minutes to generate new GPG keys. Once it completes, you will be prompted to reboot the system. At that point, you will be asked to generate a new TOTP/HOTP secret. If you didn’t change them, the default TPM owner PIN and Librem Key admin PIN are “12345678”.
Updating PureBoot Firmware¶
Purism occasionally releases 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 our coreboot releases or by running our coreboot utility. In either case, you must copy the update 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 will get an alert at the next boot to update your TOTP/HOTP secret.
Revert to PureBoot Basic¶
Since November 2023, Purism ships PureBoot on all Librem computers, defaulting to Basic mode for devices shipped without a Librem Key.
To revert to PureBoot Basic, enable Basic mode in Configuration Settings.
Switch to coreboot/SeaBIOS¶
coreboot/SeaBIOS is a supported alternative firmware for Librem Devices. Prior to November 2023, it was installed by default on devices that shipped without a Librem Key.
To switch to coreboot/SeaBIOS, use our coreboot utility. This will replace PureBoot with coreboot/SeaBIOS. You can also return to PureBoot later using the coreboot utility.