ukify(1)

.SH "NAME" ukify - Combine components into a signed Unified Kernel Image for UEFI systems

.SH "SYNOPSIS"

.HP 144u

ukify
[OPTIONS...]
build

.HP 144u

ukify
[OPTIONS...]
genkey

.HP 144u

ukify
[OPTIONS...]
inspect
FILE...

.SH "DESCRIPTION"

.PP ukify is a tool whose primary purpose is to combine components (usually a kernel, an initrd, and the systemd-stub(7) UEFI stub) to create a UAPI.5 Unified Kernel Image (UKI)[1] — a single PE binary that boots the system. When the UKI is executed, the stub extracts and boots the embedded linux kernel. The UKI can be started directly by the firmware or through a boot loader. When used with qemu[2], a UKI can also be executed through "direct kernel boot", see example below.

.PP ukify can also be used to generate other types of UKI-like images, in particular extensions. See the description of the build verb below. ukify can also generate certificates and keys for SecureBoot and PCR signing, see the description of the genkey verb below. ukify can also print detailed information about unified kernel images, see the description of inspect verb below.

.SH "COMMANDS"

.PP The following commands are understood:

.SS "build"

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

.PP 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=, DeviceTreeAuto=/--devicetree-auto=, HWIDs=/--hwids=, Splash=/--splash=, PCRPKey=/--pcrpkey=, Uname=/--uname=, SBAT=/--sbat=, and --section= below.

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

.PP If PCR signing keys are provided via the PCRPrivateKey=/--pcr-private-key= and PCRPublicKey=/--pcr-public-key= or PCRCertificate=/--pcr-certificate= 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.

.PP 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= or PCRCertificate=/--pcr-certificate=, 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 one of SigningEngine=/--signing-engine= or SigningProvider=/--signing-provider= is specified, then the private key arguments will be passed verbatim to openssl(1) as URIs, and the public key arguments will be loaded as X.509 certificates, so that signing can be performed with an OpenSSL engine or provider respectively.

.PP 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).

.PP 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[3].

.SS "genkey"

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

.PP The generated certificate's name and lifetime are set with SecureBootCertificateCommonName=/--secureboot-certificate-common-name= and SecureBootCertificateValidity=/--secureboot-certificate-validity=.

.PP The output files must not exist.

.SS "inspect"

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

.PP Also see the description of -j/--json= and --section=.

.PP Other tools that may be useful for inspect UKIs: llvm-objdump(1) -p and pe-inspect.

.SH "CONFIGURATION SETTINGS"

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

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

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

.PP The following options and settings are understood:

.SS "Command line-only options"

.PP --config=PATH

{


    "type": "devicetree",


    "name": "Example Laptop 16 Gen 7",


    "compatible": "example,laptop-16-g7",


    "hwids": [


        "5dc05bf4-01f6-4089-b464-a08c47ea9295",


        "3e3f8f3c-2003-46f2-811c-85554f7d5952"


    ]
}

uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/

uki-addon,1,UKI Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html

$ 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'

$ 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-initrd-private-key.pem \


      --pcr-public-key=tpm2-pcr-initrd-public-key.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=secureboot-private-key.pem \


      --secureboot-certificate=secureboot-certificate.pem \


      --sign-kernel \


      --cmdline='quiet rw rhgb'

$ cat ukify.conf
[UKI]
Initrd=early_cpio
Cmdline=quiet rw rhgb
SecureBootPrivateKey=secureboot-private-key.pem
SecureBootCertificate=secureboot-certificate.pem
SignKernel=yes
PCRBanks=sha384,sha512
[PCRSignature:initrd]
PCRPrivateKey=tpm2-pcr-initrd-private-key.pem
PCRPublicKey=tpm2-pcr-initrd-public-key.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

ukify build \


      --secureboot-private-key=secureboot-private-key.pem \


      --secureboot-certificate=secureboot-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

# cat >/etc/kernel/uki.conf <<EOF
[UKI]
SecureBootPrivateKey=/etc/kernel/secureboot-private-key.pem
SecureBootCertificate=/etc/kernel/secureboot-certificate.pem
[PCRSignature:initrd]
Phases=enter-initrd
PCRPrivateKey=/etc/systemd/tpm2-pcr-initrd-private-key.pem
PCRPublicKey=/etc/systemd/tpm2-pcr-initrd-public-key.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

# ukify genkey --config=/etc/kernel/uki.conf
Writing SecureBoot private key to /etc/kernel/secureboot-private-key.pem
Writing SecureBoot certificate to /etc/kernel/secureboot-certificate.pem
Writing private key for PCR signing to /etc/systemd/tpm2-pcr-initrd-private-key.pem
Writing public key for PCR signing to /etc/systemd/tpm2-pcr-initrd-public-key.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

$ ukify build \


      --profile='TITLE=Base' \


      --output=profile0.efi

$ ukify build \


      --profile='TITLE=Boot into Storage Target Mode
ID=storagetm' \


      --cmdline='quiet rw rd.systemd.unit=storage-target-mode.target' \


      --output=profile1.efi

$ ukify build \


      --profile='TITLE=Factory Reset
ID=factory-reset' \


      --cmdline='quiet rw systemd.unit=factory-reset.target' \


      --output=profile2.efi

$ 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' \


      --join-profile=profile0.efi \


      --join-profile=profile1.efi \


      --join-profile=profile2.efi \


      --output=base.efi

$ 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' \


      --pcr-public-key=tpm2-pcr-initrd-public-key.pem \


      --policy-digest \


      --sign-initrd-pcrs \


      --json=short \


      --output=base.efi >base.pcrs

#!/usr/bin/python3
import base64, json, subprocess
priv_key = '/home/zbyszek/src/systemd/tpm2-pcr-private.pem'
base_file = 'base.pcrs'
base = json.load(open(base_file))
for bank,policies in base.items():


    for policy in policies:


        tbs = base64.b16decode(policy['tbs'].upper())


        call = subprocess.run(['openssl', 'dgst', '-sha256', '-sign', priv_key],


                input=tbs,


                              check=True,


                              capture_output=True)


        sig = base64.b64encode(call.stdout).decode()


        policy['sig'] = sig
print(json.dumps(base))

$ ukify build \


      --join-pcrsig=base.efi \


      --pcrsig=@base.pcrs \


      --json=short \


      --output=base-signed.efi