# ukify

## 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. Seesystemd-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=** ,
           _DeviceTreeAuto=_ /**--devicetree-auto=** , _HWIDs=_ /**--hwids=** ,
           _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=** 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.
    
           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.
    
           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.
    
           **--policy-digest** , **--no-policy-digest**
               Enable or disable a call to systemd-measure(1) to print
               pre-calculated TPM2 policy digests. Useful for offline signing
               of PCR policies. Defaults to false.
    
               Added in version 258.
    
           **--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 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.
    
           **--join-profile=**_PATH_
               Takes a path to an existing PE file containing an additional
               profile to add to the unified kernel image. The profile can be
               generated beforehand with **ukify**. The profile does not need to
               be signed or contain PCR measurements. All UKI PE sections of
               the specified PE file are copied into the generated UKI. This
               is useful for generating multi-profile UKIs. Note that this
               only copies PE sections that are defined by the UKI
               specification, and ignores any other, for example ".text" or
               similar.
    
               Added in version 257.
    
           **--sign-profile=**_ID_
               Takes a profile ID for which signed PCR measurements should be
               generated by ukify. This option can be used together with
               **--join-profile=** when building the final unified kernel image.
               If not specified, signed PCR measurements will be added for
               all profiles.
    
               Added in version 258.
    
           **--join-pcrsig=**_PATH_ , **--pcrsig=**_TEXT_**|**_@PATH_
               **--join-pcrsig=** takes a path to an existing PE file containing
               a previously built UKI.  **--pcrsig=** takes a path to an existing
               pcrsig JSON blob, or a verbatim inline blob. They must be used
               together, and without specifying any other UKI section
               parameters.  **ukify** will attach the pcrsig JSON blob to the
               UKI. This is useful in combination with **--policy-digest** to
               create a UKI and then sign the TPM2 policy digests offline.
    
               Added in version 258.
    
           **--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.
    
           _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.
    
           _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.
    
           _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.
    
           _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.
    
           _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.
    
           _DeviceTreeAuto=PATH..._ , **--devicetree-auto=**_PATH_
               Zero or more automatically selectable DeviceTree files. In the
               configuration file, items are separated by whitespace. Each
               DeviceTree will be in a separate ".dtbauto" section.
    
               Added in version 257.
    
           _HWIDs=PATH_ , **--hwids=**_PATH_
               The hardware ID device table (the ".hwids" section). The
               argument is a path to a directory with JSON HWID device
               description files. Each file needs to contain a single JSON
               object with a "name", "compatible" and "hwids" keys. The
               "name" and "compatible" keys must have string values and the
               "hwids" key must have a list of strings as value, where the
               strings must be valid UUIDs that represent CHIDs/HWIDs.
               Example:
    
                   {
                       "type": "devicetree",
                       "name": "Example Laptop 16 Gen 7",
                       "compatible": "example,laptop-16-g7",
                       "hwids": [
                           "5dc05bf4-01f6-4089-b464-a08c47ea9295",
                           "3e3f8f3c-2003-46f2-811c-85554f7d5952"
                       ]
                   }
    
               Here "Example Laptop 16 Gen 7" is the device "name" (as
               defined by the manufacturer), "example,laptop-16-g7" is the
               "compatible" (as defined by the kernel) and "hwids" is an
               array of CHIDs/HWIDs (extracted i.e. from **fwupdtool hwids**
               output). If not specified, the section will not be present. It
               is recommended to specify this parameter if automatically
               selectable DeviceTrees are to be used.
    
               Added in version 257.
    
           _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.
    
           _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._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=** or
               _PCRCertificate=_ /**--pcr-certificate=** argument, that key will be
               used. Otherwise, the section will not be present.
    
               Added in version 253.
    
           _Profile=PATH_ , **--profile=**_PATH_
               A path to a UKI profile to place in an ".profile" section.
               This option is useful for creating multi-profile UKIs, and is
               typically used in combination with **--join-profile=** , to extend
               the specified UKI with an additional profile.
    
               Added in version 257.
    
           _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", "pesign", or "systemd-sbsign".
               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=** or
               _SigningProvider=_ /**--signing-provider=** option is used, this may
               also be an engine or provider 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=** or
               _SigningProvider=_ /**--signing-provider=** option is used, this may
               also be an engine or provider 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 OpenSSL engine to be used for signing the resulting binary
               and PCR measurements, see **openssl-engine**(1).
    
               Added in version 253.
    
           _SigningProvider=PROVIDER_ , **--signing-provider=**_PROVIDER_
               An OpenSSL provider to be used for signing the resulting
               binary and PCR measurements, see **provider**(7). This option can
               only be used when **systemd-sbsign** is used as the signing tool.
    
               Added in version 257.
    
           _CertificateProvider=PROVIDER_ , **--certificate-provider=**_PROVIDER_
               An OpenSSL provider to be used for loading the certificate
               used to sign the resulting binary and PCR measurements, see
               **provider**(7). This option can only be used when **systemd-sbsign**
               is used as the signing tool.
    
               Added in version 257.
    
           _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.
    
       **[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. Cannot be specified if **--pcr-certificate=** is used.
    
               Added in version 253.
    
           _PCRCertificate=PATH_ , **--pcr-certificate=**_PATH_
               An X.509 certificate 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. Cannot be specified if **--pcr-public-key=** is used.
    
               Added in version 258.
    
           _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=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'
    
           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-initrd-private-key.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
           secureboot-private-key.pem.
    
           **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=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
    
           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=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
    
           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/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
    
           Next, we can generate the certificate and keys:
    
               # 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
    
           (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.
    
           **Example 6. Multi-Profile UKI**
    
           First, create a few profiles:
    
               $ ukify build \
                     --profile='TITLE=Base' \
                     --output=profile0.efi
    
           Add a second profile (@1):
    
               $ ukify build \
                     --profile='TITLE=Boot into Storage Target Mode
               ID=storagetm' \
                     --cmdline='quiet rw rd.systemd.unit=storage-target-mode.target' \
                     --output=profile1.efi
    
           Add a third profile (@2):
    
               $ ukify build \
                     --profile='TITLE=Factory Reset
               ID=factory-reset' \
                     --cmdline='quiet rw systemd.unit=factory-reset.target' \
                     --output=profile2.efi
    
           Then, create a UKI and include all the generated profiles:
    
               $ 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
    
           The resulting UKI base-with-profile-0-1-2.efi will now contain
           three profiles.
    
           **Example 7. Offline signing of pcrsig section**
    
           First, create a UKI and save the PCR JSON blob:
    
               $ 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 \
                     --json=short \
                     --output=base.efi >base.pcrs
    
           Then, sign the PCR digests offline and insert them in the JSON
           blob:
    
               #!/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:
                       pol = base64.b16decode(policy['pol'].upper())
                       call = subprocess.run(['openssl', 'dgst', f'-{bank}', '-sign', priv_key],
                                             input=pol,
                                             check=True,
                                             capture_output=True)
                       sig = base64.b64encode(call.stdout).decode()
                       policy['sig'] = sig
    
               print(json.dumps(base))
    
           Finally, attach the updated JSON blob to the UKI:
    
               $ ukify build \
                     --join-pcrsig=base.efi \
                     --pcrsig=@base.pcrs \
                     --json=short \
                     --output=base-signed.efi
    
           The resulting UKI base-signed.efi will now contain the signed PCR
           digests.
    


## 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
    


* * *