sbctl − Secure Boot Manager
sbctl <command>
sbctl is a tool that allows one to create keys for secure boot, securely enroll them and keep track of files to sign.
status
Shows the current secure boot status of the system. It checks if you are currently booted in UEFI with Secure Boot, and whether Setup Mode has been enabled.
create−keys
Creates a set of signing keys used to sign EFI binaries. Currently, it will create the following keys:
• Platform Key
• Key Exchange key
• Signature Database Key
enroll−keys
Enrolls the creates key into the EFI variables. This puts the computer out of SetupMode and enables Secure Boot.
Note that some
devices have hardware firmware that is signed and
validated when Secure Boot is enabled. Failing to validate
this firmware
could brick devices. It's recommended to enroll your own
keys with
Microsoft certificates.
−m, −−microsoft
Enroll UEFI vendor certificates from Microsoft into the signature database. See Option ROM*.
−t, −−tpm−eventlog
Enroll checksums from the TPM Eventlog into the signature database. See Option ROM*.
This feature is experimental
−c, −−custom
Enroll custom KEK and db certificates from "/usr/share/secureboot/keys/custom/KEK/" and "/usr/share/secureboot/keys/custom/db/", respectively.
−f, −−firmware−builtin
Enroll signatures from dbDefault, KEKDefault or PKDefault. This is usefull if sbctl does not vendor your OEM certificates, or doesn’t include all of them.
Valid values
are "db", "KEK" or "PK" passed
as a comma
delimitered string.
Default: "db,KEK"
−−yes−this−might−brick−my−machine, −−yolo
Ignore the Option ROM error and continue enrolling keys into the UEFI firmware. See Option ROM*.
−i, −−ignore−immutable
Ignore checking /sys/firmware/efi/efivars/ for immutable files and unset the immutable attribute before enrolling certificates.
−−export
Export the keys we intend to enroll as EFI Signature Lists (esl), or EFI Authenticated Variables (auth) into the current working directory.
Valid values are: esl, auth.
−p, −−partial
Enroll keys only for the hierarchy specified.
Valid values are: db, dbx, KEK, PK.
−−custom−bytes
Enroll a custom bytefile provided by its path to the efivar specified by partial.
−a, −−append
Instead of replacing the currently enrolled keys, append the provided one.
sign <FILE>...
Signs an EFI binary with the created key. The file will be checked for valid signatures to avoid duplicates.
−o PATH, −−output PATH
Output filename. Default replaces the file.
−s, −−save
Save file to the database.
sign−all
Signs all enrolled EFI binaries.
−g, −−generate
Generate all bundles before signing.
import−keys
Imports existing keys into sbctl.
−−db−cert PATH
Path to a valid Database (db) certificate.
−−db−key PATH
Path to a valid Database (db) private key.
−−kek−cert PATH
Path to a valid Key Exchange Key (KEK) certificate.
−−kek−key PATH
Path to a valid Key Exchange Key (KEK) private key.
−−pk−cert PATH
Path to a valid Platform Key(PK) certificate.
−−pk−key PATH
Path to a valid Platform Key (PK) private key.
−−directory PATH
Path to a key directory. The expected file locations inside this directory are:
• PK/PK.key
• PK/PK.pem
• KEK/KEK.key
• KEK/KEK.pem
• db/db.key
• db/db.pem
−−force
Overwrite the existing key directory used by sbctl.
list−files, ls−files, ls
Lists all enrolled EFI binaries.
remove−file <FILE>, rm−file <FILE>, rm <FILE>
Removes the file from the signing database.
verify [FILE...]
Looks for EFI binaries with the mime type application/x−dosexec in the ESP partition, and looks at the file database. Checks if they have been signed with the Signature Database Key. Takes an optional file argument to check specific files.
reset
Resets the Platform Key. This sets the machine out of Secure Boot mode and allows key rotation.
−p, −−partial
Reset keys only for the hierarchy specified.
Valid values are: db, dbx, KEK, PK.
rotate−keys
Rotate the secure boot keys and replace them with newly generated keys. Saves the old keys to a directory in /var/tmp and resigns any files from the file database.
−−backup−dir PATH
Choose backup directory for old keys.
−p, −−partial
Rotate keys only for the hierarchy specified.
Valid values are: db, dbx, KEK, PK.
−k, −−key−file
Key file to be appended for the specified hierarchy.
−c, −−cert−file
Certificate file to be appended for the specified hierarchy.
help
Displays a help message.
bundle [FLAGS] <NAME>
Creates a bundle that should produce EFI binaries. See BUNDLES below for more details.
−a PATH, −−amducode PATH
AMD microcode location.
−c PATH, −−cmdline PATH
Cmdline location. (default "/etc/kernel/cmdline")
−e PATH, −−efi−stub PATH
EFI Stub location. (default "/usr/lib/systemd/boot/efi/linuxx64.efi.stub")
−p PATH, −−esp PATH
ESP location. (default "/efi")
−h, −−help
Help for bundle.
−f PATH, −−initramfs PATH
Initramfs location. (default "/boot/initramfs−linux.img")
−i PATH, −−intelucode PATH
Intel microcode location.
−k PATH, −−kernel−img PATH
Kernel image location. (default "/boot/vmlinuz−linux")
−o PATH, −−os−release PATH
OS Release file location. (default "/usr/lib/os−release")
−s, −−save
Save bundle to the database.
−l PATH, −−splash−img PATH
Boot splash image location.
generate−bundles
This command generates all bundles.
−s, −−sign
Sign all the generated bundles.
remove−bundle <NAME>, rm−bundle <NAME>
Removes a bundle from the list. This does not delete the bundle itself.
list−bundles, ls−bundle
List all registered bundles to generate.
−j, −−json
This enables supported commands to output their values in json instead of human−readable text. This is practical for parsing data with tools like jq.
Normally, only the kernel is signed with your secure boot keys. This means the kernel command line and initramfs can be changed without possibility of verification.
Bundles are EFI executables which pack all three (initramfs, kernel and cmdline) into a single file which is easy to sign. Avoiding any unsigned files during boot makes the whole process more tamper−proof.
When a bundle is generated, its configuration is stored into the bundle database (see FILES). Subsequent executions of sbctl generate−bundles will rebuild these bundles, so you don’t need to re−specify all parameters after each system update.
Tip: systemd−boot will automatically show entries for any bundles found in esp/EFI/Linux/*.efi.
See https://github.com/Foxboron/sbctl/wiki/FAQ#option−rom
Note: To use custom Secure Boot keys it’s important to reboot into firmware setup (systemctl reboot −−firmware−setup) and navigate into the Secure Boot menu to enter Setup Mode. This is normally achieved by deleting/clearing the secure boot keys (or at a minimum the Platform Key) while leaving secure boot mode enabled. Some firmwares have a Custom Mode which only disables signature verification and should therefore not be enabled unless no other way to enter key management is provided. If this step is not completed, enrolling custom keys will be rejected by the firmware.
Next is creating the keys for secure boot. create−keys creates the key hierarchy needed for secure boot into "/usr/share/secureboot".
$
sbctl create−keys
Created Owner UUID
a9fbbdb7−a05f−48d5−b63a−08c5df45ee70
Creating secure boot keys...â
Secure boot keys created!
Next up is enrolling the keys into the efi firmware. sbctl supports doing this on a live system instead of having to boot or run a key management tool from the UEFI shell.
Note: This can fail because of firmware issues and unique options in the machine BIOS menu.
$
sbctl enroll−keys
Enrolling keys to EFI variables...â
Enrolled keys to the EFI variables!
After we have successfully enrolled the keys, we need to sign our current boot chain. Traditionally on UEFI systems one can have an EFI System Partition (ESP) on /efi, /boot or /boot/efi. One can usually find the correct one by looking at mount points or finding the EFI directory on the ESP.
The most important file to sign is the kernel. This location differs between distributions but can usually be found on the ESP or /boot. We use −−save to store the file path, so we don’t need to manually sign it later.
Note that sbctl can only keep track of file paths. On versioned kernels this might prove tricky.
$
sbctl sign −−save /efi/vmlinuz−linux
â Signed /efi/vmlinuz−linux
Next is to sign the bootloader. This can usually be found on the standard path below, but might differ between installations.
$
sbctl sign −−save /efi/EFI/BOOT/BOOTX64.EFI
â Signed /efi/EFI/BOOT/BOOTX64.EFI
sbctl is able to find and verify the ESP, along with any saved files to verify we have signed the files we need.
$
sbctl verify
Verifying file database and EFI images in /efi...
â /efi/EFI/BOOT/BOOTX64.EFI is signed
â /efi/vmlinuz−linux is signed
Once we have confirmed everything works, we can reboot. Once we have logged back in, we can verify the state of the system. There should be no need to re−enable Secure Boot or enter User Mode in the firmware.
$
sbctl status
Installed: â sbctl is installed
Owner GUID:
a7b893cc−949d−408c−b5cc−6e7d0370fdb6
Setup Mode: â Disabled
Secure Boot: â Enabled
When we do a system update, we can run sign−all to resign all the saved files from earlier.
$
sbctl sign−all
File has already been signed /boot/vmlinuz−linux
â Signed /efi/EFI/BOOT/BOOTX64.EFI
sbctl supports creating unified kernel images. These UEFI executables bundles the initramfs, kernel and cmdline into one executable which can be signed for secure boot. This allows you to authenticate larger parts of the bootchain instead of only signing the kernel.
$
sbctl bundle −i /boot/intel−ucode.img
−l /usr/share/systemd/bootctl/splash−arch.bmp
−k /boot/vmlinuz−linux
−f /boot/initramfs−linux−lts.img
−c /etc/kernel/cmdline
/efi/EFI/Linux/linux−linux.efi
Note that dracut(8) and mkinitcpio(8) supports unified kernel features, and they should be preferred over the sbctl implementation. It is mostly provided in the cases where this feature is not supported by the initramfs generator of the distribution.
All commands that take path arguments convert them into absolute paths when saving them to the database.
On success, 0 is returned, a non−zero failure code otherwise.
SYSTEMD_ESP_PATH, ESP_PATH
Defines the EFI system partition (ESP) location. This overrides the behaviour from sbctl where we query for the correct partition with lsblk. No checks are performed on this path and can be usefull for testing purposes.
SBCTL_UNICODE
If this value is "0" sbctl will replace the unicode symbols to equivalent ascii ones. The default value is assumed to be 1.
/usr/share/secureboot
Default storage directory.
/usr/share/secureboot/GUID
Owner identification. This is a randomly generated UUID.
/usr/share/secureboot/files.db
Contains a list of EFI binaries to be signed by the generated key.
/usr/share/secureboot/bundles.db
Contains a list of EFI bundles to be generated.
/usr/share/secureboot/keys/db/db.{pem,key}
Contains the Signature Database key used for signing EFI binaries.
/usr/share/secureboot/keys/KEK/KEK.{pem,key}
Contains the Key Exchange Key.
/usr/share/secureboot/keys/PK/PK.{pem,key}
Contains the Platform Key.
/usr/share/secureboot/keys/custom/KEK/*
Contains custom certificates which will be added to the firmware as additional Key Exchange Keys.
/usr/share/secureboot/keys/custom/db/*
Contains custom certificates which will be added to the firmware Signature Database.
bootctl(1) jq(1)
• Morten Linderud <[email protected] [1] >