sbkeysync & maintaining uefi key databases

Over the last couple of weeks I've been working on a set of secure-boot tools. Originally, this project was intended as a quick implementation of an EFI-image-signing utility, but it has since grown a little. I've now added code to help maintain the UEFI signature databases from within a running OS.

A new utility, sbkeysync, reads the current EFI signature databases from firmware, and reads a set of keys from a standard location in the filesystem - for example, /etc/secureboot/keys. It then updates the firmware key databases with any keys that are not already present.

A filesystem keystore will look something like this:

/etc/secureboot/keys/PK/<pk-file>

/etc/secureboot/keys/KEK/<kek-file-1>

/etc/secureboot/keys/KEK/<kek-file-2>

/etc/secureboot/keys/KEK/…

/etc/secureboot/keys/db/<db-file-1>

/etc/secureboot/keys/db/<db-file-2>

/etc/secureboot/keys/db/…

/etc/secureboot/keys/dbx/<dbx-file-1>

/etc/secureboot/keys/dbx/<dbx-file-2>

/etc/secureboot/keys/dbx/…

These files need to be in a certain format: signed EFI_SIGNATURE_LIST data.
There's two other utilities in the sbtools tree to help to create the key files: sbsiglist and sbvarsign. The following example shows how you'd use these tools to do a basic secure boot key configuration.

An example key setup

If you're interested in trying sbkeysync, the following guide should get you set up. To start, you'll need:

A machine with firmware that implements UEFI secure boot, configured to be in setup mode (ie, no PK installed).

Be warned that you're playing with three different layers of development code here: the secure boot tools are new, the efivars implementation hasn't had a lot of review yet, and firmware secure boot implementations are still fairly recent too. I'd recommend against doing this testing on a production machine.

We'll also need a GUID to represent the "key owner". Just generate one with uuidgen.

[jk@pecola ~]$ guid=$(uuidgen)
[jk@pecola ~]$ echo $guid

generating key updates

In order to install this key into the firmware signature databases, we need to create an EFI_SIGNATURE_LIST container for the key, and provide an EFI_VARIABLE_AUTHENTICATION_2 descriptor. The update data will be self-signed, to keep things simple.

Next, we create a signed update for the EFI signature databases. The signed update consists of the certificate, prefixed with an EFI_VARIABLE_AUTHENTICATION_2 descriptor.
The authentication descriptor signs the key data, plus the variable name and attributes. Becuase the variable name is included, we need to generate a separate signed update for each variable (PK, KEK and db):

The output will list the keys were found in the EFI key databases, keys found in the filesystem keystore, and which keys should be inserted to the EFI key databases to bring them in sync with the keystore.

If all looks good, we can remove the --dry-run argument to actually update the firmware key databases. However, be careful here - once a PK is enrolled, the machine is no longer in setup mode, and secure boot is enforced. At the very least, ensure that your firmware setup screens have a facility for returning your machine to setup mode, and/or removing the PK.

Note that some firmware implementations may require a reboot for the changes to take effect in the EFI variables. Before you do this though, you'll probably want to sign your bootloader, so that you can actually boot something!

signing a bootloader

Now that secure boot is enabled, it'd be nice if we actually had something to boot. Although it isn't recommended for production systems, we'll just sign the GRUB2 binary that's already there:

However, I have not been able to reset the PK on all firmware implementations so far; there may be bugs in the signing tools (or firmware) that prevent the update from being properly verified. Because of this, I strongly suggest checking for the facility to clear the PK through your firmware setup screens before attempting to set the PK.

secure boot tools resources

If you'd like to check out the code, the following links may be useful: