From: Zbigniew Jędrzejewski-Szmek Date: Mon, 12 Jun 2023 10:22:32 +0000 (+0200) Subject: man/ukify: add structure to describe verbs, document genkey X-Git-Tag: v254-rc1~207^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a3f758b3104ee1161d2dbf5a8c1be653340b1672;p=thirdparty%2Fsystemd.git man/ukify: add structure to describe verbs, document genkey This just adds two paragraphs of text, but moves a lot of the text one level down into a subsection. --- diff --git a/man/ukify.xml b/man/ukify.xml index 6895301d016..33d9d26d2de 100644 --- a/man/ukify.xml +++ b/man/ukify.xml @@ -35,60 +35,83 @@ 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 components (usually a kernel, an initrd, and a - UEFI boot stub) to create a + 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. + + + + + <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 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. - + The output files must not exist. +