table of contents
UKIFY(1) | ukify | UKIFY(1) |
NAME¶
ukify - Combine components into a signed Unified Kernel Image for UEFI systems
SYNOPSIS¶
ukify [OPTIONS...] build
ukify [OPTIONS...] genkey
ukify [OPTIONS...] inspect FILE...
DESCRIPTION¶
ukify is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and a UEFI boot stub) to create a Unified Kernel Image (UKI)[1] — a PE binary that can be executed by the firmware to start the embedded linux kernel. See systemd-stub(7) for details about the stub.
COMMANDS¶
The following commands are understood:
build¶
This command creates a Unified Kernel Image. The two primary options that should be specified for the build verb are Linux=/--linux=, and Initrd=/--initrd=. Initrd= accepts multiple whitespace-separated paths and --initrd= can be specified multiple times.
Additional sections will be inserted into the UKI, either automatically or only if a specific option is provided. See the discussions of Microcode=/--microcode=, Cmdline=/--cmdline=, OSRelease=/--os-release=, DeviceTree=/--devicetree=, Splash=/--splash=, PCRPKey=/--pcrpkey=, Uname=/--uname=, SBAT=/--sbat=, and --section= below.
ukify can also be used to assemble a PE binary that is not executable but contains auxiliary data, for example additional kernel command line entries.
If PCR signing keys are provided via the PCRPrivateKey=/--pcr-private-key= and PCRPublicKey=/--pcr-public-key= options, PCR values that will be seen after booting with the given kernel, initrd, and other sections, will be calculated, signed, and embedded in the UKI. systemd-measure(1) is used to perform this calculation and signing.
The calculation of PCR values is done for specific boot phase paths. Those can be specified with the Phases=/--phases= option. If not specified, the default provided by systemd-measure is used. It is also possible to specify the PCRPrivateKey=/--pcr-private-key=, PCRPublicKey=/--pcr-public-key=, and Phases=/--phases= arguments more than once. Signatures will then be performed with each of the specified keys. On the command line, when both --phases= and --pcr-private-key= are used, they must be specified the same number of times, and then the n-th boot phase path set will be signed by the n-th key. This can be used to build different trust policies for different phases of the boot. In the config file, PCRPrivateKey=, PCRPublicKey=, and Phases= are grouped into separate sections, describing separate boot phases. If SigningEngine=/--signing-engine= is specified, then the private keys arguments will be passed verbatim to OpenSSL as URIs, and the public key arguments will be loaded as X.509 certificates, so that signing can be performed with an OpenSSL engine.
If a SecureBoot signing key is provided via the SecureBootPrivateKey=/--secureboot-private-key= option, the resulting PE binary will be signed as a whole, allowing the resulting UKI to be trusted by SecureBoot. Also see the discussion of automatic enrollment in systemd-boot(7).
If the stub and/or the kernel contain ".sbat" sections they will be merged in the UKI so that revocation updates affecting either are considered when the UKI is loaded by Shim. For more information on SBAT see Shim documentation[2].
genkey¶
This command creates the keys for PCR signing and the key and certificate used for SecureBoot signing. The same configuration options that determine what keys and in which paths will be needed for signing when build is used, here determine which keys will be created. See the discussion of PCRPrivateKey=/--pcr-private-key=, PCRPublicKey=/--pcr-public-key=, and SecureBootPrivateKey=/--secureboot-private-key= below.
The output files must not exist.
inspect¶
Display information about the sections in a given binary or binaries. If --all is given, all sections are shown. Otherwise, if --section= option is specified at least once, only those sections are shown. Otherwise, well-known sections that are typically included in an UKI are shown. For each section, its name, size, and sha256-digest is printed. For text sections, the contents are printed.
Also see the description of -j/--json= and --section=.
Other tools that may be useful for inspect UKIs: llvm-objdump(1) -p and pe-inspect.
CONFIGURATION SETTINGS¶
Settings can appear in configuration files (the syntax with SomeSetting=value) and on the command line (the syntax with --some-setting=value). For some command line parameters, a single-letter shortcut is also allowed. In the configuration files, the setting must be in the appropriate section, so the descriptions are grouped by section below. When the same setting appears in the configuration file and on the command line, generally the command line setting has higher priority and overwrites the config file setting completely. If some setting behaves differently, this is described below.
If no config file is provided via the option --config=PATH, ukify will try to look for a default configuration file in the following paths in this order: /etc/systemd/ukify.conf, /run/systemd/ukify.conf, /usr/local/lib/systemd/ukify.conf, and /usr/lib/systemd/ukify.conf, and then load the first one found. ukify will proceed normally if no configuration file is specified and no default one is found.
The LINUX and INITRD positional arguments, or the equivalent Linux= and Initrd= settings, are optional. If more than one initrd is specified, they will all be combined into a single PE section. This is useful to, for example, prepend microcode before the actual initrd.
The following options and settings are understood:
Command line-only options¶
--config=PATH
Added in version 254.
--measure, --no-measure
Added in version 253.
--section=NAME:TEXT|@PATH, --section=NAME:text|binary[@PATH]
For the inspect verb, the second syntax is used. The section NAME will be inspected (if found). If the second argument is "text", the contents will be printed. If the third argument is given, the contents will be saved to the file named PATH.
Note that the name is used as-is, and if the section name should start with a dot, it must be included in NAME.
Added in version 253.
--tools=DIRS
Added in version 253.
--output=FILENAME
Added in version 253.
--summary
Added in version 254.
--all
Added in version 255.
--json
Added in version 255.
-h, --help
--version
[UKI] section¶
Linux=LINUX, --linux=LINUX
Added in version 254.
Initrd=INITRD..., --initrd=LINUX
Added in version 254.
Microcode=UCODE, --microcode=UCODE
Added in version 256.
Cmdline=TEXT|@PATH, --cmdline=TEXT|@PATH
Added in version 253.
OSRelease=TEXT|@PATH, --os-release=TEXT|@PATH
Added in version 253.
DeviceTree=PATH, --devicetree=PATH
Added in version 253.
Splash=PATH, --splash=PATH
Added in version 253.
PCRPKey=PATH, --pcrpkey=PATH
Added in version 253.
Uname=VERSION, --uname=VERSION
Added in version 253.
PCRBanks=PATH, --pcr-banks=PATH
Added in version 253.
SecureBootSigningTool=SIGNER, --signtool=SIGNER
Added in version 254.
SecureBootPrivateKey=SB_KEY, --secureboot-private-key=SB_KEY
Added in version 253.
SecureBootCertificate=SB_CERT, --secureboot-certificate=SB_CERT
Added in version 253.
SecureBootCertificateDir=SB_PATH, --secureboot-certificate-dir=SB_PATH
Added in version 254.
SecureBootCertificateName=SB_CERTNAME, --secureboot-certificate-name=SB_CERTNAME
Added in version 254.
SecureBootCertificateValidity=DAYS, --secureboot-certificate-validity=DAYS
Added in version 254.
SigningEngine=ENGINE, --signing-engine=ENGINE
Added in version 253.
SignKernel=BOOL, --sign-kernel, --no-sign-kernel
Added in version 253.
SBAT=TEXT|@PATH, --sbat=TEXT|@PATH
Added in version 254.
[PCRSignature:NAME] section¶
In the config file, those options are grouped by section. On the command line, they must be specified in the same order. The sections specified in both sources are combined.
PCRPrivateKey=PATH, --pcr-private-key=PATH
Added in version 253.
PCRPublicKey=PATH, --pcr-public-key=PATH
On the command line, this option may be specified more than once, similarly to the --pcr-private-key= option. If not present, the public keys will be extracted from the private keys. On the command line, if present, this option must be specified the same number of times as the --pcr-private-key= option.
Added in version 253.
Phases=LIST, --phases=LIST
On the command line, when this argument is present, it must appear the same number of times as the --pcr-private-key= option.
Added in version 253.
EXAMPLES¶
Example 1. Minimal invocation
$ ukify build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
--cmdline='quiet rw'
This creates an unsigned UKI ./vmlinuz.unsigned.efi.
Example 2. All the bells and whistles
$ ukify build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=early_cpio \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img \
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
uki.author.myimage,1,UKI for System,uki.author.myimage,1,https://uapi-group.org/specifications/specs/unified_kernel_image/' \
--pcr-private-key=tpm2-pcr-private-key-initrd.pem \
--pcr-public-key=tpm2-pcr-public-key-initrd.pem \
--phases='enter-initrd' \
--pcr-private-key=tpm2-pcr-private-key-system.pem \
--pcr-public-key=tpm2-pcr-public-key-system.pem \
--phases='enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit \
enter-initrd:leave-initrd:sysinit:ready' \
--pcr-banks=sha384,sha512 \
--secureboot-private-key=sb.key \
--secureboot-certificate=sb.cert \
--sign-kernel \
--cmdline='quiet rw rhgb'
This creates a signed UKI ./vmlinuz.signed.efi. The initrd section contains two concatenated parts, early_cpio and initramfs-6.0.9-300.fc37.x86_64.img. The policy embedded in the ".pcrsig" section will be signed for the initrd (the enter-initrd phase) with the key tpm2-pcr-private-key-initrd.pem, and for the main system (phases leave-initrd, sysinit, ready) with the key tpm2-pcr-private-key-system.pem. The Linux binary and the resulting combined image will be signed with the SecureBoot key sb.key.
Example 3. All the bells and whistles, via a config file
This is the same as the previous example, but this time the configuration is stored in a file:
$ cat ukify.conf [UKI] Initrd=early_cpio Cmdline=quiet rw rhgb SecureBootPrivateKey=secure-boot-key.pem SecureBootCertificate=secure-boot-certificate.pem SignKernel=yes PCRBanks=sha384,sha512 [PCRSignature:initrd] PCRPrivateKey=tpm2-pcr-private-key-initrd.pem PCRPublicKey=tpm2-pcr-public-key-initrd.pem Phases=enter-initrd [PCRSignature:system] PCRPrivateKey=tpm2-pcr-private-key-system.pem PCRPublicKey=tpm2-pcr-public-key-system.pem Phases=enter-initrd:leave-initrd
enter-initrd:leave-initrd:sysinit
enter-initrd:leave-initrd:sysinit:ready $ ukify -c ukify.conf build \
--linux=/lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \
--initrd=/some/path/initramfs-6.0.9-300.fc37.x86_64.img
One "initrd" (early_cpio) is specified in the config file, and the other initrd (initramfs-6.0.9-300.fc37.x86_64.img) is specified on the command line. This may be useful for example when the first initrd contains microcode for the CPU and does not need to be updated when the kernel version changes, unlike the actual initrd.
Example 4. Kernel command line PE addon
ukify build \
--secureboot-private-key=secure-boot-key.pem \
--secureboot-certificate=secure-boot-certificate.pem \
--cmdline='debug' \
--sbat='sbat,1,SBAT Version,sbat,1,https://github.com/rhboot/shim/blob/main/SBAT.md
uki-addon.author,1,UKI Addon for System,uki-addon.author,1,https://www.freedesktop.org/software/systemd/man/systemd-stub.html'
--output=debug.addon.efi
This creates a signed PE binary that contains the additional kernel command line parameter "debug" with SBAT metadata referring to the owner of the addon.
Example 5. Decide signing policy, and create certificate and keys
First, let's create a configuration file that specifies what signatures shall be made:
# cat >/etc/kernel/uki.conf <<EOF [UKI] SecureBootPrivateKey=/etc/kernel/secure-boot-key.pem SecureBootCertificate=/etc/kernel/secure-boot-certificate.pem [PCRSignature:initrd] Phases=enter-initrd PCRPrivateKey=/etc/systemd/tpm2-pcr-private-key-initrd.pem PCRPublicKey=/etc/systemd/tpm2-pcr-public-key-initrd.pem [PCRSignature:system] Phases=enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit
enter-initrd:leave-initrd:sysinit:ready PCRPrivateKey=/etc/systemd/tpm2-pcr-private-key-system.pem PCRPublicKey=/etc/systemd/tpm2-pcr-public-key-system.pem EOF
Next, we can generate the certificate and keys:
# ukify genkey --config=/etc/kernel/uki.conf Writing SecureBoot private key to /etc/kernel/secure-boot-key.pem Writing SecureBoot certificate to /etc/kernel/secure-boot-certificate.pem Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-initrd.pem Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-initrd.pem Writing private key for PCR signing to /etc/systemd/tpm2-pcr-private-key-system.pem Writing public key for PCR signing to /etc/systemd/tpm2-pcr-public-key-system.pem
(Both operations need to be done as root to allow write access to /etc/kernel/.)
Subsequent invocations using the config file (ukify build --config=/etc/kernel/uki.conf) will use this certificate and key files. Note that the kernel-install(8) plugin 60-ukify.install uses /etc/kernel/uki.conf by default, so after this file has been created, installations of kernels that create a UKI on the local machine using kernel-install will perform signing using this config.
SEE ALSO¶
systemd(1), systemd-stub(7), systemd-boot(7), systemd-measure(1), systemd-pcrphase.service(8)
NOTES¶
- 1.
- Unified Kernel Image (UKI)
- 2.
- Shim documentation
systemd 256.8 |