diff --git a/man/ukify.xml b/man/ukify.xml index c6bfbdc9d9..6aa136298d 100644 --- a/man/ukify.xml +++ b/man/ukify.xml @@ -44,212 +44,302 @@ 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=/, 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 and - 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. + 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 option. If not specified, the default provided by - systemd-measure is used. It is also possible to specify the - , , and - arguments more than once. Signatures will be then performed with each of the specified keys. 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. + 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 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 + 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. - Options + Configuration settings - The LINUX and INITRD positional arguments are - optional. If more than one INITRD are specified, they will all be combined into - a single PE section. This is useful to for example prepend microcode before the actual initrd. + 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. - The following options are understood: + 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: - Specify 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. - + + Commandline-only options - - + + + - Specify 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. - + 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 + commandline option does not fully override the config file setting are explicitly mentioned in the + descriptions of individual options. + - - + + + - Specify 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. - + Enable or disable a call to systemd-measure to print + pre-calculated PCR values. Defaults to false. + - - + + - Specify 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. - - + Specify an arbitrary additional section + NAME. Note that the name is used as-is, and if the + section name should start with a dot, it must be included in 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. + - - + + - Specify a path to a public key to embed in the .pcrpkey section. - If not specified, and there's exactly one argument, that key will - be used. Otherwise, the section will not be present. - + 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. + - - + + - 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. - + 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. + - - + + - Specify an arbitrary additional section - NAME. Note that the name is used as-is, and if the - section name should start with a dot, it must be included in 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. - + Print a summary of loaded config and exit. This is useful to check how the options + form the configuration file and the commandline are combined. + - - + + + + - Specify a private key to use for signing PCR policies. This option may be specified - more than once, in which case multiple signatures will be made. - + + [UKI] section - - + + + Linux=LINUX + positional argument LINUX - Specify a public key to use for signing PCR policies. 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. If present, the this option must be specified - the same number of times as the option. - + A path to the kernel binary. + - - + + Initrd=INITRD... + positional argument INITRD - A comma or space-separated list of colon-separated phase paths to sign a policy for. - If not present, the default of - systemd-measure1 - will be used. When this argument is present, it must appear the same number of times as the - option. Each set of boot phase paths will be signed with the - corresponding private key. - + 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 + - 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. - + 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 + - A path to a private key to use for signing of the resulting binary. If the - option is used, this may also be an engine-specific - designation. - + 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 + - A path to a certificate to use for signing of the resulting binary. If the - option is used, this may also be an engine-specific - designation. - + 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 + - An "engine" to for signing of the resulting binary. This option is currently passed - verbatim to the option of - sbsign1. - - + 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 + - 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 option and the binary has not already - been signed. If is specified, and the binary has already been signed, - the signature will be appended anyway. - + 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 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. - + 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 + - Enable or disable a call to systemd-measure to print - pre-calculated PCR values. Defaults to false. - + 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. + - - + + SecureBootPrivateKey=SB_KEY + - 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. - + 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. + - - - + + 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. + + + + SigningEngine=ENGINE + + + An "engine" to 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. + + + + + + [PCRSignature:<replaceable>NAME</replaceable>] section + + In the config file, those options are grouped by section. On the commandline, 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 commandline, 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 commandline, 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 commandline, if present, the 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 commandline, when this argument is present, it must appear the same number of times as + the option. + + + @@ -258,7 +348,7 @@ Minimal invocation - ukify \ + $ ukify \ /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ /some/path/initramfs-6.0.9-300.fc37.x86_64.img \ --cmdline='quiet rw' @@ -270,7 +360,7 @@ All the bells and whistles - /usr/lib/systemd/ukify \ + # /usr/lib/systemd/ukify \ /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ early_cpio \ /some/path/initramfs-6.0.9-300.fc37.x86_64.img \ @@ -299,6 +389,45 @@ 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 +SecureBootCerificate=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 + +# /usr/lib/systemd/ukify -c ukify.conf \ + /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ + /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 commandline. 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 @@ -309,7 +438,8 @@ --output=debug.cmdline.efi - This creates a signed PE binary that contains an additional kernel command line parameter. + This creates a signed PE binary that contains the additional kernel command line parameter + debug. @@ -319,6 +449,7 @@ systemd1, systemd-stub7, systemd-boot7, + systemd-measure1, systemd-pcrphase.service8