'\" t
.\"     Title: sbctl
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/24/2024
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "SBCTL" "8" "01/24/2024" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sbctl \- Secure Boot Manager
.SH "SYNOPSIS"
.sp
\fBsbctl\fR <command>
.SH "DESCRIPTION"
.sp
\fBsbctl\fR is a tool that allows one to create keys for secure boot, securely enroll them and keep track of files to sign\&.
.SH "EFI SIGNING COMMANDS"
.PP
\fBstatus\fR
.RS 4
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\&.
.RE
.PP
\fBcreate\-keys\fR
.RS 4
Creates a set of signing keys used to sign EFI binaries\&. Currently, it will create the following keys:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Platform Key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Key Exchange Key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Signature Database Key
.PP
\fB\-e\fR, \fB\-\-export\fR
.RS 4
The directory to persist the exported keys\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Default: "/usr/share/secureboot/keys/"
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-d\fR, \fB\-\-database\-path\fR
.RS 4
Path to save the GUID file when generating keys\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Default: "/usr/share/secureboot/"
.fi
.if n \{\
.RE
.\}
.RE
.RE
.RE
.PP
\fBenroll\-keys\fR
.RS 4
Enrolls the created key into the EFI variables\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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\*(Aqs recommended to enroll your own keys with
Microsoft certificates\&.
.fi
.if n \{\
.RE
.\}
.PP
\fB\-m\fR, \fB\-\-microsoft\fR
.RS 4
Enroll UEFI vendor certificates from Microsoft into the signature database\&. See
\fBOption ROM\fR*\&.
.RE
.PP
\fB\-t\fR, \fB\-\-tpm\-eventlog\fR
.RS 4
Enroll checksums from the TPM Eventlog into the signature database\&. See
\fBOption ROM\fR*\&.
.sp
.if n \{\
.RS 4
.\}
.nf
This feature is experimental
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-c\fR, \fB\-\-custom\fR
.RS 4
Enroll custom KEK and db certificates from "/usr/share/secureboot/keys/custom/KEK/", "/usr/share/secureboot/keys/custom/db/", respectively\&.
.RE
.PP
\fB\-f\fR, \fB\-\-firmware\-builtin\fR
.RS 4
Enroll signatures from dbDefault, KEKDefault or PKDefault\&. This is usefull if sbctl does not vendor your OEM certificates, or doesn\(cqt include all of them\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Valid values are "db", "KEK" or "PK" passed as a comma
delimitered string\&.
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
Default: "db,KEK"
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-\-yes\-this\-might\-brick\-my\-machine\fR, \fB\-\-yolo\fR
.RS 4
Ignore the Option ROM error and continue enrolling keys into the UEFI firmware\&. See
\fBOption ROM\fR*\&.
.RE
.PP
\fB\-i\fR, \fB\-\-ignore\-immutable\fR
.RS 4
Ignore checking
/sys/firmware/efi/efivars/
for immutable files and unset the immutable attribute before enrolling certificates\&.
.RE
.PP
\fB\-\-export\fR
.RS 4
Export the keys we intend to enroll as EFI Signature Lists (esl), or EFI Authenticated Variables (auth) into the current working directory\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Valid values are: esl, auth\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-p\fR, \fB\-\-partial\fR
.RS 4
Enroll keys only for the hierarchy specified\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Valid values are: db, KEK, PK\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-\-custom\-bytes\fR
.RS 4
Enroll a custom bytefile provided by its path to the efivar specified by partial\&.
.RE
.PP
\fB\-a\fR, \fB\-\-append\fR
.RS 4
Instead of replacing the currently enrolled keys, append the provided one\&.
.RE
.RE
.PP
\fBsign\fR <FILE>\&...
.RS 4
Signs an EFI binary with the created key\&. The file will be checked for valid signatures to avoid duplicates\&.
.PP
\fB\-o\fR \fIPATH\fR, \fB\-\-output\fR \fIPATH\fR
.RS 4
Output filename\&. Default replaces the file\&.
.RE
.PP
\fB\-s\fR, \fB\-\-save\fR
.RS 4
Save file to the database\&.
.RE
.RE
.PP
\fBsign\-all\fR
.RS 4
Signs all enrolled EFI binaries\&.
.PP
\fB\-g\fR, \fB\-\-generate\fR
.RS 4
Generate all bundles before signing\&.
.RE
.RE
.PP
\fBimport\-keys\fR
.RS 4
Imports existing keys into sbctl\&.
.PP
\fB\-\-db\-cert\fR \fIPATH\fR
.RS 4
Path to a valid Database (db) certificate\&.
.RE
.PP
\fB\-\-db\-key\fR \fIPATH\fR
.RS 4
Path to a valid Database (db) private key\&.
.RE
.PP
\fB\-\-kek\-cert\fR \fIPATH\fR
.RS 4
Path to a valid Key Exchange Key (KEK) certificate\&.
.RE
.PP
\fB\-\-kek\-key\fR \fIPATH\fR
.RS 4
Path to a valid Key Exchange Key (KEK) private key\&.
.RE
.PP
\fB\-\-pk\-cert\fR \fIPATH\fR
.RS 4
Path to a valid Platform Key(PK) certificate\&.
.RE
.PP
\fB\-\-pk\-key\fR \fIPATH\fR
.RS 4
Path to a valid Platform Key (PK) private key\&.
.RE
.PP
\fB\-\-directory\fR \fIPATH\fR
.RS 4
Path to a key directory\&. The expected file locations inside this directory are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
PK/PK\&.key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
PK/PK\&.pem
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
KEK/KEK\&.key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
KEK/KEK\&.pem
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
db/db\&.key
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
db/db\&.pem
.RE
.RE
.PP
\fB\-\-force\fR
.RS 4
Overwrite the existing key directory used by sbctl\&.
.RE
.RE
.PP
\fBlist\-files\fR, \fBls\-files\fR, \fBls\fR
.RS 4
Lists all enrolled EFI binaries\&.
.RE
.PP
\fBremove\-file\fR <FILE>, \fBrm\-file\fR <FILE>, \fBrm\fR <FILE>
.RS 4
Removes the file from the signing database\&.
.RE
.PP
\fBverify\fR [FILE\&...]
.RS 4
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\&.
.RE
.PP
\fBreset\fR
.RS 4
Resets the Platform Key\&. This sets the machine out of Secure Boot mode and allows key rotation\&.
.PP
\fB\-p\fR, \fB\-\-partial\fR
.RS 4
Reset keys only for the hierarchy specified\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Valid values are: db, KEK, PK\&.
.fi
.if n \{\
.RE
.\}
.RE
.RE
.PP
\fBrotate\-keys\fR
.RS 4
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\&.
.PP
\fB\-\-backup\-dir\fR \fIPATH\fR
.RS 4
Choose backup directory for old keys\&.
.RE
.PP
\fB\-p\fR, \fB\-\-partial\fR
.RS 4
Rotate keys only for the hierarchy specified\&.
.sp
.if n \{\
.RS 4
.\}
.nf
Valid values are: db, KEK, PK\&.
.fi
.if n \{\
.RE
.\}
.RE
.PP
\fB\-k\fR, \fB\-\-key\-file\fR
.RS 4
Key file to be appended for the specified hierarchy\&.
.RE
.PP
\fB\-c\fR, \fB\-\-cert\-file\fR
.RS 4
Certificate file to be appended for the specified hierarchy\&.
.RE
.RE
.PP
\fBhelp\fR
.RS 4
Displays a help message\&.
.RE
.SH "EFI BINARY COMMANDS"
.PP
\fBbundle\fR [\fIFLAGS\fR] <NAME>
.RS 4
Creates a bundle that should produce EFI binaries\&. See
\fBBUNDLES\fR
below for more details\&.
.PP
\fB\-a\fR \fIPATH\fR, \fB\-\-amducode\fR \fIPATH\fR
.RS 4
AMD microcode location\&.
.RE
.PP
\fB\-c\fR \fIPATH\fR, \fB\-\-cmdline\fR \fIPATH\fR
.RS 4
Cmdline location\&. (default "/etc/kernel/cmdline")
.RE
.PP
\fB\-e\fR \fIPATH\fR, \fB\-\-efi\-stub\fR \fIPATH\fR
.RS 4
EFI Stub location\&. (default "/usr/lib/systemd/boot/efi/linuxx64\&.efi\&.stub")
.RE
.PP
\fB\-p\fR \fIPATH\fR, \fB\-\-esp\fR \fIPATH\fR
.RS 4
ESP location\&. (default "/efi")
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Help for bundle\&.
.RE
.PP
\fB\-f\fR \fIPATH\fR, \fB\-\-initramfs\fR \fIPATH\fR
.RS 4
Initramfs location\&. (default "/boot/initramfs\-linux\&.img")
.RE
.PP
\fB\-i\fR \fIPATH\fR, \fB\-\-intelucode\fR \fIPATH\fR
.RS 4
Intel microcode location\&.
.RE
.PP
\fB\-k\fR \fIPATH\fR, \fB\-\-kernel\-img\fR \fIPATH\fR
.RS 4
Kernel image location\&. (default "/boot/vmlinuz\-linux")
.RE
.PP
\fB\-o\fR \fIPATH\fR, \fB\-\-os\-release\fR \fIPATH\fR
.RS 4
OS Release file location\&. (default "/usr/lib/os\-release")
.RE
.PP
\fB\-s\fR, \fB\-\-save\fR
.RS 4
Save bundle to the database\&.
.RE
.PP
\fB\-l\fR \fIPATH\fR, \fB\-\-splash\-img\fR \fIPATH\fR
.RS 4
Boot splash image location\&.
.RE
.RE
.PP
\fBgenerate\-bundles\fR
.RS 4
This command generates all bundles\&.
.PP
\fB\-s\fR, \fB\-\-sign\fR
.RS 4
Sign all the generated bundles\&.
.RE
.RE
.PP
\fBremove\-bundle\fR <NAME>, \fBrm\-bundle\fR <NAME>
.RS 4
Removes a bundle from the list\&. This does not delete the bundle itself\&.
.RE
.PP
\fBlist\-bundles\fR, \fBls\-bundle\fR
.RS 4
List all registered bundles to generate\&.
.RE
.SH "OPTIONS"
.PP
\fB\-j\fR, \fB\-\-json\fR
.RS 4
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\&.
.RE
.SH "BUNDLES"
.sp
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\&.
.sp
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\&.
.sp
When a bundle is generated, its configuration is stored into the bundle database (see \fBFILES\fR)\&. Subsequent executions of \fBsbctl generate\-bundles\fR will rebuild these bundles, so you don\(cqt need to re\-specify all parameters after each system update\&.
.sp
Tip: systemd\-boot will automatically show entries for any bundles found in \fBesp/EFI/Linux/*\&.efi\fR\&.
.SH "OPTION ROM"
.sp
See https://github\&.com/Foxboron/sbctl/wiki/FAQ#option\-rom
.SH "USAGE"
.sp
\fINote\fR: To use custom Secure Boot keys it\(cqs important to reboot into firmware setup (systemctl reboot \-\-firmware\-setup) and navigate into the \fISecure Boot\fR menu to enter \fISetup Mode\fR\&. 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 \fICustom Mode\fR 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\&.
.sp
Next is creating the keys for secure boot\&. \fIcreate\-keys\fR creates the key hierarchy needed for secure boot into "/usr/share/secureboot"\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl create\-keys
Created Owner UUID a9fbbdb7\-a05f\-48d5\-b63a\-08c5df45ee70
Creating secure boot keys\&.\&.\&.✔
Secure boot keys created!
.fi
.if n \{\
.RE
.\}
.sp
Next up is enrolling the keys into the efi firmware\&. \fBsbctl\fR supports doing this on a live system instead of having to boot or run a key management tool from the UEFI shell\&.
.sp
\fINote\fR: This can fail because of firmware issues and unique options in the machine BIOS menu\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl enroll\-keys
Enrolling keys to EFI variables\&.\&.\&.✔
Enrolled keys to the EFI variables!
.fi
.if n \{\
.RE
.\}
.sp
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 (\fIESP\fR) on \fI/efi\fR, \fI/boot\fR or \fI/boot/efi\fR\&. One can usually find the correct one by looking at mount points or finding the \fIEFI\fR directory on the ESP\&.
.sp
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 \fI\-\-save\fR to store the file path, so we don\(cqt need to manually sign it later\&.
.sp
Note that \fBsbctl\fR can only keep track of file paths\&. On versioned kernels this might prove tricky\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl sign \-\-save /efi/vmlinuz\-linux
✔ Signed /efi/vmlinuz\-linux
.fi
.if n \{\
.RE
.\}
.sp
Next is to sign the bootloader\&. This can usually be found on the standard path below, but might differ between installations\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl sign \-\-save /efi/EFI/BOOT/BOOTX64\&.EFI
✔ Signed /efi/EFI/BOOT/BOOTX64\&.EFI
.fi
.if n \{\
.RE
.\}
.sp
\fBsbctl\fR is able to find and verify the ESP, along with any saved files to verify we have signed the files we need\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl verify
Verifying file database and EFI images in /efi\&.\&.\&.
✔ /efi/EFI/BOOT/BOOTX64\&.EFI is signed
✔ /efi/vmlinuz\-linux is signed
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl status
Installed:  ✓ sbctl is installed
Owner GUID: a7b893cc\-949d\-408c\-b5cc\-6e7d0370fdb6
Setup Mode: ✓ Disabled
Secure Boot:    ✓ Enabled
.fi
.if n \{\
.RE
.\}
.sp
When we do a system update, we can run \fIsign\-all\fR to resign all the saved files from earlier\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ sbctl sign\-all
File has already been signed /boot/vmlinuz\-linux
✓ Signed /efi/EFI/BOOT/BOOTX64\&.EFI
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
$ 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
.fi
.if n \{\
.RE
.\}
.sp
Note that \fBdracut\fR(8) and \fBmkinitcpio\fR(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\&.
.SH "NOTES"
.sp
All commands that take path arguments convert them into absolute paths when saving them to the database\&.
.SH "EXIT STATUS"
.sp
On success, 0 is returned, a non\-zero failure code otherwise\&.
.SH "ENVIRONMENT VARIABLES"
.PP
\fBSYSTEMD_ESP_PATH\fR, \fBESP_PATH\fR
.RS 4
Defines the EFI system partition (ESP) location\&. This overrides the behaviour from
\fBsbctl\fR
where we query for the correct partition with
\fBlsblk\fR\&. No checks are performed on this path and can be usefull for testing purposes\&.
.RE
.PP
\fBSBCTL_UNICODE\fR
.RS 4
If this value is "0" sbctl will replace the unicode symbols to equivalent ascii ones\&. The default value is assumed to be 1\&.
.RE
.SH "FILES"
.PP
\fB/usr/share/secureboot\fR
.RS 4
Default storage directory\&.
.RE
.PP
\fB/usr/share/secureboot/GUID\fR
.RS 4
Owner identification\&. This is a randomly generated UUID\&.
.RE
.PP
\fB/usr/share/secureboot/files\&.db\fR
.RS 4
Contains a list of EFI binaries to be signed by the generated key\&.
.RE
.PP
\fB/usr/share/secureboot/bundles\&.db\fR
.RS 4
Contains a list of EFI bundles to be generated\&.
.RE
.PP
\fB/usr/share/secureboot/keys/db/db\&.{pem,key}\fR
.RS 4
Contains the Signature Database key used for signing EFI binaries\&.
.RE
.PP
\fB/usr/share/secureboot/keys/KEK/KEK\&.{pem,key}\fR
.RS 4
Contains the Key Exchange Key\&.
.RE
.PP
\fB/usr/share/secureboot/keys/PK/PK\&.{pem,key}\fR
.RS 4
Contains the Platform Key\&.
.RE
.PP
\fB/usr/share/secureboot/keys/custom/KEK/\fR*
.RS 4
Contains custom certificates which will be added to the firmware as additional Key Exchange Keys\&.
.RE
.PP
\fB/usr/share/secureboot/keys/custom/db/\fR*
.RS 4
Contains custom certificates which will be added to the firmware Signature Database\&.
.RE
.SH "SEE ALSO"
.sp
\fBbootctl\fR(1) \fBjq\fR(1)
.SH "AUTHORS"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Morten Linderud <morten@linderud\&.pw>
.RE