NAME¶

sbctl - Secure Boot Manager

SYNOPSIS¶

sbctl <command>

DESCRIPTION¶

sbctl is a tool that allows one to create keys for secure boot, securely enroll them and keep track of files to sign.

EFI SIGNING COMMANDS¶

status

create-keys

enroll-keys

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.

sign <FILE>...

sign-all

import-keys

list-files, ls-files, ls

remove-file <FILE>, rm-file <FILE>, rm <FILE>

list-enrolled-keys, ls-enrolled-keys

verify [FILE...]

reset

rotate-keys

export-enrolled-keys

setup

This commands enables declarative configuration of sbctl through the
configuration file. It can also print the current configuration and the
current state of the installation.

help

EFI BINARY COMMANDS¶

bundle [FLAGS] <NAME>

generate-bundles

remove-bundle <NAME>, rm-bundle <NAME>

list-bundles, ls-bundle

OPTIONS¶

-j, --json

-c, --config

--disable-landlock

--debug

BUNDLES¶

Note: This is being deprecated. Please move to dracut/mkinitcpio/ukify.

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.

SUPPORTED KEY TYPES¶

sbctl currently supports storing keys as plain unencrypted files, or as TPM shielded keys.

Plain unencrypted files (file) should only be used when the root partition is encrypted. This is the default key type for historic reasons. File keys are hardcoded to RSA 4096.

TPM shielded keys (tpm) are shielded inside the TPM and available if there is an accessible TPM on the system. TPM policies are not supported which means we can’t seal keys towards the system state. Note that TPM keys are hardcoded to RSA 2048, which is usually the highest bit strength supported by TPMs.

When creating a key hierarchy for Secure Boot, the user can decide which key type each of the keys in the hierarchy gets. Because TPMs can be slow to sign, it’s generally adviced to keep PK and KEK in the TPM, while the db key can be a standard file key.

Note that password protection is currently not supported.

LANDLOCK¶

sbctl supports landlock and will attempt to restrict access to filepaths to where it’s needed during execution. Any attempts at establishing network access is also restricted.

This feature can be disabled by setting landlock: false in the configuration file, or by passing --disable-landlock to sbctl.

OPTION ROM¶

See https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom

USAGE¶

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 "/var/lib/sbctl/keys".

# 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. Also, 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 using the -m option. See Option ROM* above.

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

NOTES¶

All commands that take path arguments convert them into absolute paths when saving them to the database.

EXIT STATUS¶

On success, 0 is returned, a non-zero failure code otherwise.

ENVIRONMENT VARIABLES¶

SYSTEMD_ESP_PATH, ESP_PATH

SBCTL_UNICODE

FILES¶

/etc/sbctl/sbctl.conf:; Defautl configuration file. See sbctl.conf(5)

/var/lib/sbctl

/var/lib/sbctl/GUID

/var/lib/sbctl/files.db

/var/lib/sbctl/bundles.db

/var/lib/sbctl/keys/db/db.{pem,key}

/var/lib/sbctl/keys/KEK/KEK.{pem,key}

/var/lib/sbctl/keys/PK/PK.{pem,key}

/var/lib/sbctl/keys/custom/KEK/*

/var/lib/sbctl/keys/custom/db/*

SEE ALSO¶

bootctl(1) jq(1) sbctl.conf(5) landlock(7)

AUTHORS¶