sbctl(8)
========

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**::
        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.

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

**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**::
        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.

**reset**::
        Resets the Platform Key. This sets the machine out of Secure Boot mode
        and allows key rotation.

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

**help**::
        Displays a help message.


EFI binary commands
------------------

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


Options
-------

**-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`.


Bundles
-------

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


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 "/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 linkman:dracut[8] and linkman: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**::
        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.


Files
----
**/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.


See Also
--------
linkman:bootctl[1]
linkman:jq[1]

Authors
-------

* Morten Linderud <morten@linderud.pw>
