Provided by: systemd-ukify_256.4-2ubuntu1_all bug

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
           Load configuration from the given config file. In general, settings specified in the
           config file have lower precedence than the settings specified via options. In cases
           where the command line option does not fully override the config file setting are
           explicitly mentioned in the descriptions of individual options.

           Added in version 254.

       --measure, --no-measure
           Enable or disable a call to systemd-measure(1) to print pre-calculated PCR values.
           Defaults to false.

           Added in version 253.

       --section=NAME:TEXT|@PATH, --section=NAME:text|binary[@PATH]
           For all verbs except inspect, the first syntax is used. Specify an arbitrary
           additional section "NAME". The argument may be a literal string, or "@" followed by a
           path name. This option may be specified more than once. Any sections specified in this
           fashion will be inserted (in order) before the ".linux" section which is always last.

           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 file 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
           Specify one or more directories with helper tools.  ukify will look for helper tools
           in those directories first, and if not found, try to load them from $PATH in the usual
           fashion.

           Added in version 253.

       --output=FILENAME
           The output filename. If not specified, the name of the LINUX argument, with the suffix
           ".unsigned.efi" or ".signed.efi" will be used, depending on whether signing for
           SecureBoot was performed.

           Added in version 253.

       --summary
           Print a summary of loaded config and exit. This is useful to check how the options
           from the configuration file and the command line are combined.

           Added in version 254.

       --all
           Print all sections (with inspect verb).

           Added in version 255.

       --json
           Generate JSON output (with inspect verb).

           Added in version 255.

       -h, --help
           Print a short help text and exit.

       --version
           Print a short version string and exit.

   [UKI] section
       Linux=LINUX, --linux=LINUX
           A path to the kernel binary.

           Added in version 254.

       Initrd=INITRD..., --initrd=LINUX
           Zero or more initrd paths. In the configuration file, items are separated by
           whitespace. The initrds are combined in the order of specification, with the initrds
           specified in the config file first.

           Added in version 254.

       Microcode=UCODE, --microcode=UCODE
           Path to initrd containing microcode updates. If not specified, the section will not be
           present.

           Added in version 256.

       Cmdline=TEXT|@PATH, --cmdline=TEXT|@PATH
           The kernel command line (the ".cmdline" section). The argument may be a literal
           string, or "@" followed by a path name. If not specified, no command line will be
           embedded.

           Added in version 253.

       OSRelease=TEXT|@PATH, --os-release=TEXT|@PATH
           The os-release description (the ".osrel" section). The argument may be a literal
           string, or "@" followed by a path name. If not specified, the os-release(5) file will
           be picked up from the host system.

           Added in version 253.

       DeviceTree=PATH, --devicetree=PATH
           The devicetree description (the ".dtb" section). The argument is a path to a compiled
           binary DeviceTree file. If not specified, the section will not be present.

           Added in version 253.

       Splash=PATH, --splash=PATH
           A picture to display during boot (the ".splash" section). The argument is a path to a
           BMP file. If not specified, the section will not be present.

           Added in version 253.

       PCRPKey=PATH, --pcrpkey=PATH
           A path to a public key to embed in the ".pcrpkey" section. If not specified, and
           there's exactly one PCRPublicKey=/--pcr-public-key= argument, that key will be used.
           Otherwise, the section will not be present.

           Added in version 253.

       Uname=VERSION, --uname=VERSION
           Specify the kernel version (as in uname -r, the ".uname" section). If not specified,
           an attempt will be made to extract the version string from the kernel image. It is
           recommended to pass this explicitly if known, because the extraction is based on
           heuristics and not very reliable. If not specified and extraction fails, the section
           will not be present.

           Added in version 253.

       PCRBanks=PATH, --pcr-banks=PATH
           A comma or space-separated list of PCR banks to sign a policy for. If not present, all
           known banks will be used ("sha1", "sha256", "sha384", "sha512"), which will fail if
           not supported by the system.

           Added in version 253.

       SecureBootSigningTool=SIGNER, --signtool=SIGNER
           Whether to use "sbsign" or "pesign". Depending on this choice, different parameters
           are required in order to sign an image. Defaults to "sbsign".

           Added in version 254.

       SecureBootPrivateKey=SB_KEY, --secureboot-private-key=SB_KEY
           A path to a private key to use for signing of the resulting binary. If the
           SigningEngine=/--signing-engine= option is used, this may also be an engine-specific
           designation. This option is required by
           SecureBootSigningTool=sbsign/--signtool=sbsign.

           Added in version 253.

       SecureBootCertificate=SB_CERT, --secureboot-certificate=SB_CERT
           A path to a certificate to use for signing of the resulting binary. If the
           SigningEngine=/--signing-engine= option is used, this may also be an engine-specific
           designation. This option is required by
           SecureBootSigningTool=sbsign/--signtool=sbsign.

           Added in version 253.

       SecureBootCertificateDir=SB_PATH, --secureboot-certificate-dir=SB_PATH
           A path to a nss certificate database directory to use for signing of the resulting
           binary. Takes effect when SecureBootSigningTool=pesign/--signtool=pesign is used.
           Defaults to /etc/pki/pesign.

           Added in version 254.

       SecureBootCertificateName=SB_CERTNAME, --secureboot-certificate-name=SB_CERTNAME
           The name of the nss certificate database entry to use for signing of the resulting
           binary. This option is required by SecureBootSigningTool=pesign/--signtool=pesign.

           Added in version 254.

       SecureBootCertificateValidity=DAYS, --secureboot-certificate-validity=DAYS
           Period of validity (in days) for a certificate created by genkey. Defaults to 3650,
           i.e. 10 years.

           Added in version 254.

       SigningEngine=ENGINE, --signing-engine=ENGINE
           An "engine" for signing of the resulting binary. This option is currently passed
           verbatim to the --engine= option of sbsign(1).

           Added in version 253.

       SignKernel=BOOL, --sign-kernel, --no-sign-kernel
           Override the detection of whether to sign the Linux binary itself before it is
           embedded in the combined image. If not specified, it will be signed if a SecureBoot
           signing key is provided via the SecureBootPrivateKey=/--secureboot-private-key= option
           and the binary has not already been signed. If SignKernel=/--sign-kernel is true, and
           the binary has already been signed, the signature will be appended anyway.

           Added in version 253.

       SBAT=TEXT|@PATH, --sbat=TEXT|@PATH
           SBAT metadata associated with the UKI or addon. SBAT policies are useful to revoke
           whole groups of UKIs or addons with a single, static policy update that does not take
           space in DBX/MOKX. If not specified manually, a default metadata entry consisting of
           "uki,1,UKI,uki,1,https://uapi-group.org/specifications/specs/unified_kernel_image/"
           for UKIs and "uki-addon,1,UKI
           Addon,addon,1,https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html"
           for addons will be used, to ensure it is always possible to revoke them. For more
           information on SBAT see Shim documentation[2].

           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
           A private key to use for signing PCR policies. On the command line, this option may be
           specified more than once, in which case multiple signatures will be made.

           Added in version 253.

       PCRPublicKey=PATH, --pcr-public-key=PATH
           A public key to use for signing PCR policies.

           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
           A comma or space-separated list of colon-separated phase paths to sign a policy for.
           Each set of boot phase paths will be signed with the corresponding private key. If not
           present, the default of systemd-measure(1) will be used.

           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=pcr-private-initrd-key.pem \
                 --pcr-public-key=pcr-public-initrd-key.pem \
                 --phases='enter-initrd' \
                 --pcr-private-key=pcr-private-system-key.pem \
                 --pcr-public-key=pcr-public-system-key.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 pcr-private-initrd-key.pem, and for the main system (phases leave-initrd,
       sysinit, ready) with the key pcr-private-system-key.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=sb.key
           SecureBootCertificate=sb.cert
           SignKernel=yes
           PCRBanks=sha384,sha512

           [PCRSignature:initrd]
           PCRPrivateKey=pcr-private-initrd-key.pem
           PCRPublicKey=pcr-public-initrd-key.pem
           Phases=enter-initrd

           [PCRSignature:system]
           PCRPrivateKey=pcr-private-system-key.pem
           PCRPublicKey=pcr-public-system-key.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=sb.key \
                 --secureboot-certificate=sb.cert \
                 --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.cert.pem

           [PCRSignature:initrd]
           Phases=enter-initrd
           PCRPrivateKey=/etc/kernel/pcr-initrd.key.pem
           PCRPublicKey=/etc/kernel/pcr-initrd.pub.pem

           [PCRSignature:system]
           Phases=enter-initrd:leave-initrd enter-initrd:leave-initrd:sysinit
                  enter-initrd:leave-initrd:sysinit:ready
           PCRPrivateKey=/etc/kernel/pcr-system.key.pem
           PCRPublicKey=/etc/kernel/pcr-system.pub.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.cert.pem
           Writing private key for PCR signing to /etc/kernel/pcr-initrd.key.pem
           Writing public key for PCR signing to /etc/kernel/pcr-initrd.pub.pem
           Writing private key for PCR signing to /etc/kernel/pcr-system.key.pem
           Writing public key for PCR signing to /etc/kernel/pcr-system.pub.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)
           https://uapi-group.org/specifications/specs/unified_kernel_image/

        2. Shim documentation
           https://github.com/rhboot/shim/blob/main/SBAT.md