ukify(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | CONFIGURATION SETTINGS | EXAMPLES | SEE ALSO | NOTES | COLOPHON

UKIFY(1)                          ukify                         UKIFY(1)

NAME         top

       ukify - Combine components into a signed Unified Kernel Image for
       UEFI systems

SYNOPSIS         top


       ukify [OPTIONS...] build

       ukify [OPTIONS...] genkey

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

DESCRIPTION         top

       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         top

       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         top

       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         top

       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 auxiliary PE

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

       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 an config 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         top

       systemd(1), systemd-stub(7), systemd-boot(7), systemd-measure(1),
       systemd-pcrphase.service(8)

NOTES         top

        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

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

systemd 257~devel                                               UKIFY(1)

Pages that refer to this page: systemd-measure(1)systemd.directives(7)systemd.index(7)systemd-stub(7)kernel-install(8)