From 0fdf4e181025b98df2e52ff3c861dc35d0412b8c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 25 Nov 2022 16:25:23 +0100 Subject: [PATCH] man: add man page for ukify --- man/rules/meson.build | 1 + man/ukify.xml | 307 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 308 insertions(+) create mode 100644 man/ukify.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index bb7799036d8..442640a4dc0 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -1189,6 +1189,7 @@ manpages = [ ''], ['udev_new', '3', ['udev_ref', 'udev_unref'], ''], ['udevadm', '8', [], ''], + ['ukify', '1', [], 'HAVE_GNU_EFI'], ['user@.service', '5', ['systemd-user-runtime-dir', 'user-runtime-dir@.service'], diff --git a/man/ukify.xml b/man/ukify.xml new file mode 100644 index 00000000000..3cc13a4cba2 --- /dev/null +++ b/man/ukify.xml @@ -0,0 +1,307 @@ + + + + + + + + ukify + systemd + + + + ukify + 1 + + + + ukify + Combine kernel and initrd into a signed Unified Kernel Image + + + + + /usr/lib/systemd/ukify + LINUX + INITRD + OPTIONS + + + + + Description + + Note: this command is experimental for now. While it is intended to become a regular component of + systemd, it might still change in behaviour and interface. + + ukify is a tool that combines a kernel and an initrd with + 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. + + Additional sections will be inserted into the UKI, either automatically or only if a specific + option is provided. See the discussions of + , + , + , + , + , + , + and + below. + + 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. + 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 + 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. + + 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 + systemd-boot7. + + + + + Options + + Note that the LINUX and INITRD positional + arguments are mandatory. + + The following options 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. + + + + + + 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. + + + + + + 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. + + + + + + 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 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 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. + + + + + + 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 private key to use for signing PCR policies. This option may be specified + more than once, in which case multiple signatures will be made. + + + + + + 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 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. + + + + + + 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. + + + + + + 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. + + + + + + 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. + + + + + + An "engine" to for signing of the resulting binary. This option is currently passed + verbatim to the option of + sbsign1. + + + + + + + + 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. + + + + + + Specify a directory with helper tools. ukify will look for helper + tools in that directory first, and if not found, try to load them from $PATH in + the usual fashion. + + + + + + + Enable or disable a call to systmed-measure to print + pre-calculated PCR values. Defaults to false. + + + + + + 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. + + + + + + + + + Examples + + + Minimal invocation + + 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' + + + This creates an unsigned UKI ./vmlinuz.unsigned.efi. + + + + All the bells and whistles + + /usr/lib/systemd/ukify \ + /lib/modules/6.0.9-300.fc37.x86_64/vmlinuz \ + /some/path/initramfs-6.0.9-300.fc37.x86_64.img \ + --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 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. + + + + + See Also + + systemd1, + systemd-stub7, + systemd-boot7, + objcopy1, + systemd-pcrphase.service1 + + + + -- 2.47.3