From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/ukify.xml | 686 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 686 insertions(+) create mode 100644 man/ukify.xml (limited to 'man/ukify.xml') diff --git a/man/ukify.xml b/man/ukify.xml new file mode 100644 index 0000000..9b7e209 --- /dev/null +++ b/man/ukify.xml @@ -0,0 +1,686 @@ + + + + + + + + ukify + systemd + + + + ukify + 1 + + + + ukify + Combine components into a signed Unified Kernel Image for UEFI systems + + + + + 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) + — a PE binary that can be executed by the firmware to start the embedded linux kernel. + See systemd-stub7 + for details about the stub. + + + + Commands + + The following commands are understood: + + + <command>build</command> + + This command creates a Unified Kernel Image. The two primary options that should be specified for + the build verb are Linux=/, and + Initrd=/. Initrd= accepts multiple + whitespace-separated paths and 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 + Cmdline=/, + OSRelease=/, + DeviceTree=/, + Splash=/, + PCRPKey=/, + Uname=/, + SBAT=/, + and + 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=/ and + PCRPublicKey=/ 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-measure1 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=/ option. If not specified, the default provided + by systemd-measure is used. It is also possible to specify the + PCRPrivateKey=/, + PCRPublicKey=/, and + Phases=/ arguments more than once. Signatures will then be + performed with each of the specified keys. On the command line, when both and + 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 a SecureBoot signing key is provided via the + SecureBootPrivateKey=/ 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-boot7. + + + 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. + + + + + <command>genkey</command> + + 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=/, + PCRPublicKey=/, and + SecureBootPrivateKey=/ below. + + The output files must not exist. + + + + <command>inspect</command> + + Display information about the sections in a given binary or binaries. + If is given, all sections are shown. + Otherwise, if 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 / and + . + + + + + Configuration settings + + Settings can appear in configuration files (the syntax with SomeSetting=value) and on the command line (the syntax + with ). 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 , + ukify will try to look for a default configuration file in the following paths in this + order: /run/systemd/ukify.conf, /etc/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 + + + + + + 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. + + + + + + + + + Enable or disable a call to + systemd-measure1 + to print pre-calculated PCR values. Defaults to false. + + + + + + + + + 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. + + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + 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. + + + + + + + + Print all sections (with inspect verb). + + + + + + + + Generate JSON output (with inspect verb). + + + + + + + + + + + [UKI] section + + + + Linux=LINUX + + + A path to the kernel binary. + + + + + + Initrd=INITRD... + + + 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. + + + + + + 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. + + + + + + OSRelease=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-release5 file + will be picked up from the host system. + + + + + + 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. + + + + + + + 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. + + + + + + + PCRPKey=PATH + + + A path to a public key to embed in the .pcrpkey section. If not + specified, and there's exactly one + PCRPublicKey=/ argument, that key will be used. + Otherwise, the section will not be present. + + + + + + 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. + + + + + + PCRBanks=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. + + + + + + SecureBootSigningTool=SIGNER + + + Whether to use sbsign or pesign. + Depending on this choice, different parameters are required in order to sign an image. + Defaults to sbsign. + + + + + + SecureBootPrivateKey=SB_KEY + + + A path to a private key to use for signing of the resulting binary. If the + SigningEngine=/ option is used, this may also be + an engine-specific designation. This option is required by + SecureBootSigningTool=sbsign/. + + + + + + SecureBootCertificate=SB_CERT + + + A path to a certificate to use for signing of the resulting binary. If the + SigningEngine=/ option is used, this may also + be an engine-specific designation. This option is required by + SecureBootSigningTool=sbsign/. + + + + + + SecureBootCertificateDir=SB_PATH + + + A path to a nss certificate database directory to use for signing of the resulting binary. + Takes effect when SecureBootSigningTool=pesign/ is used. + Defaults to /etc/pki/pesign. + + + + + + SecureBootCertificateName=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/. + + + + + + SecureBootCertificateValidity=DAYS + + + Period of validity (in days) for a certificate created by + genkey. Defaults to 3650, i.e. 10 years. + + + + + + SigningEngine=ENGINE + + + An "engine" for signing of the resulting binary. This option is currently passed + verbatim to the option of + sbsign1. + + + + + + + SignKernel=BOOL + + + + 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=/ option and the + binary has not already been signed. If + SignKernel=/ is true, and the binary has already + been signed, the signature will be appended anyway. + + + + + + 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://www.freedesktop.org/software/systemd/man/systemd-stub.html + will be used, to ensure it is always possible to revoke UKIs and addons. For more information on + SBAT see Shim documentation. + + + + + + + + + [PCRSignature:<replaceable>NAME</replaceable>] 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 + + + 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. + + + + + + PCRPublicKey=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 + 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 option. + + + + + + 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-measure1 + will be used. + + On the command line, when this argument is present, it must appear the same number of times as + the option. + + + + + + + + + Examples + + + 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. + + + + 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://www.freedesktop.org/software/systemd/man/systemd-stub.html' \ + --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. + + + + 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. + + + + 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. + + + + 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 +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-install8 + 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 + + systemd1, + systemd-stub7, + systemd-boot7, + systemd-measure1, + systemd-pcrphase.service8 + + + + -- cgit v1.2.3