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/systemd-measure.xml | 388 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 388 insertions(+) create mode 100644 man/systemd-measure.xml (limited to 'man/systemd-measure.xml') diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml new file mode 100644 index 0000000..ff3abc4 --- /dev/null +++ b/man/systemd-measure.xml @@ -0,0 +1,388 @@ + + + + + + + + systemd-measure + systemd + + + + systemd-measure + 1 + + + + systemd-measure + Pre-calculate and sign expected TPM2 PCR values for booted unified kernel images + + + + + /usr/lib/systemd/systemd-measure OPTIONS + + + + + Description + + Note: this command is experimental for now. While it is likely to become a regular component of + systemd, it might still change in behaviour and interface. + + systemd-measure is a tool that may be used to pre-calculate and sign the + expected TPM2 PCR 11 values that should be seen when a Linux Unified Kernel Image + (UKI) based on + systemd-stub7 is + booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel + command line file, + os-release5 file, boot + splash file, and TPM2 PCR PEM public key file that make up the unified kernel image, and determines the + PCR values expected to be in place after booting the image. Calculation starts with a zero-initialized + PCR 11, and is executed in a fashion compatible with what systemd-stub does at boot. + The result may optionally be signed cryptographically, to allow TPM2 policies that can only be unlocked + if a certain set of kernels is booted, for which such a PCR signature can be provided. + + It usually doesn't make sense to call this tool directly when constructing a UKI. Instead, + ukify1 should be used; + it will invoke systemd-measure and take care of embedding the resulting measurements + into the UKI. + + + + Commands + + The following commands are understood: + + + + status + + This is the default command if none is specified. This queries the local system's + TPM2 PCR 11+12+13 values and displays them. The data is written in a similar format as the + calculate command below, and may be used to quickly compare expectation with + reality. + + + + + + calculate + + Pre-calculate the expected values seen in PCR register 11 after boot-up of a unified + kernel image consisting of the components specified with , + , , , + , , , + , see below. Only is + mandatory. (Alternatively, specify to use the current values of PCR + register 11 instead.) + + + + + + + sign + + As with the calculate command, pre-calculate the expected value + seen in TPM2 PCR register 11 after boot-up of a unified kernel image. Then, cryptographically sign + the resulting values with the private/public key pair (RSA) configured via + and . This will write a JSON object to + standard output that contains signatures for all specified PCR banks (see the + option below), which may be used to unlock encrypted credentials (see + systemd-creds1) or + LUKS volumes (see + systemd-cryptsetup@.service8). + This allows binding secrets to a set of kernels for which such PCR 11 signatures can be + provided. + + Note that a TPM2 device must be available for this signing to take place, even though the + result is not tied to any TPM2 device or its state. + + + + + + + + Options + + The following options are understood: + + + + + + + + + + + + + + When used with the calculate or sign verb, + configures the files to read the unified kernel image components from. Each option corresponds with + the equally named section in the unified kernel PE file. The switch expects + the path to the ELF kernel file that the unified PE kernel will wrap. All switches except + are optional. Each option may be used at most once. + + + + + + + When used with the calculate or sign verb, + takes the PCR 11 values currently in effect for the system (which should typically reflect the hashes + of the currently booted kernel). This can be used in place of and the other + switches listed above. + + + + + + + + Controls the PCR banks to pre-calculate the PCR values for – in case + calculate or sign is invoked –, or the banks to show in the + status output. May be used more then once to specify multiple banks. If not + specified, defaults to the four banks sha1, sha256, + sha384, sha512. + + + + + + + + + These switches take paths to a pair of PEM encoded RSA key files, for use with + the sign command. + + Note the difference between the and + switches. The former selects the data to include in the .pcrpkey PE section of the + unified kernel image, the latter picks the public key of the key pair used to sign the resulting PCR + 11 values. The former is the key that the booted system will likely use to lock disk and credential + encryption to, the latter is the key used for unlocking such resources again. Hence, typically the + same PEM key should be supplied in both cases. + + If the is not specified but is + specified the public key is automatically derived from the private key. + + + + + + PATH + + Controls which TPM2 device to use. Expects a device node path referring to the TPM2 + chip (e.g. /dev/tpmrm0). Alternatively the special value auto + may be specified, in order to automatically determine the device node of a suitable TPM2 device (of + which there must be exactly one). The special value list may be used to enumerate + all suitable TPM2 devices currently discovered. + + + + + + PHASE + + Controls which boot phases to calculate expected PCR 11 values for. This takes a + series of colon-separated strings that encode boot "paths" for entering a specific phase of the boot + process. Each of the specified strings is measured by the + systemd-pcrphase-initrd.service, + systemd-pcrphase-sysinit.service, and + systemd-pcrphase.service8 + into PCR 11 during different milestones of the boot process. This switch may be specified multiple + times to calculate PCR values for multiple boot phases at once. If not used defaults to + enter-initrd, enter-initrd:leave-initrd, + enter-initrd:leave-initrd:sysinit, + enter-initrd:leave-initrd:sysinit:ready, i.e. calculates expected PCR values for + the boot phase in the initrd, during early boot, during later boot, and during system runtime, but + excluding the phases before the initrd or when shutting down. This setting is honoured both by + calculate and sign. When used with the latter it's particularly + useful for generating PCR signatures that can only be used for unlocking resources during specific + parts of the boot process. + + For further details about PCR boot phases, see + systemd-pcrphase.service8. + + + + + + PATH + + When generating a PCR JSON signature (via the sign command), + combine it with a previously generated PCR JSON signature, and output it as one. The specified path + must refer to a regular file that contains a valid JSON PCR signature object. The specified file is + not modified. It will be read first, then the newly generated signature appended to it, and the + resulting object is written to standard output. Use this to generate a single JSON object consisting + from signatures made with a number of signing keys (for example, to have one key per boot phase). The + command will suppress duplicates: if a specific signature is already included in a JSON signature + object it is not added a second time. + + + + + + + + + + + + + Examples + + + Generate a unified kernel image, and calculate the expected TPM PCR 11 value + + $ ukify --output=vmlinux.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ + --splash=splash.bmp \ + --devicetree=devicetree.dtb \ + --measure \ + vmlinux initrd.cpio +11:sha1=d775a7b4482450ac77e03ee19bda90bd792d6ec7 +11:sha256=bc6170f9ce28eb051ab465cd62be8cf63985276766cf9faf527ffefb66f45651 +11:sha384=1cf67dff4757e61e5...7f49ad720be02fd07263e1f93061243aec599d1ee4b4 +11:sha512=8e79acd3ddbbc8282...0c3e8ec0c714821032038f525f744960bcd082d937da + + + ukify1 + internally calls systemd-measure. The output with hashes is from + systemd-measure. + + + + Generate a private/public key pair, a unified kernel image, and a TPM PCR 11 signature for + it, and embed the signature and the public key in the image + + $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem +..+.+++++++++......+.........+......+.......+....+.....+.+...+.......... +$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem +# systemd-measure sign \ + --linux=vmlinux \ + --osrel=os-release.txt \ + --cmdline=cmdline.txt \ + --initrd=initrd.cpio \ + --splash=splash.bmp \ + --dtb=devicetree.dtb \ + --pcrpkey=tpm2-pcr-public.pem \ + --bank=sha1 \ + --bank=sha256 \ + --private-key=tpm2-pcr-private.pem \ + --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json +# ukify --output=vmlinuz.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ + --splash=splash.bmp \ + --devicetree=devicetree.dtb \ + --pcr-private-key=tpm2-pcr-private.pem \ + --pcr-public-key=tpm2-pcr-public.pem \ + --pcr-banks=sha1,sha256 \ + vmlinux initrd.cpio + + Later on, enroll the signed PCR policy on a LUKS volume: + + # systemd-cryptenroll --tpm2-device=auto \ + --tpm2-public-key=tpm2-pcr-public.pem \ + --tpm2-signature=tpm2-pcr-signature.json \ + /dev/sda5 + + And then unlock the device with the signature: + + # systemd-cryptsetup attach \ + volume5 /dev/sda5 - \ + tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json + + Note that when the generated unified kernel image vmlinux.efi is booted, the + signature and public key files will be placed at locations systemd-cryptenroll and + systemd-cryptsetup will look for anyway, and thus these paths do not actually need to + be specified. + + + + Introduce a second public key, signing the same kernel PCR measurements, but only for the initrd boot phase + + This example extends the previous one, but we now introduce a second signing key that is only + used to sign PCR policies restricted to the initrd boot phase. This can be used to lock down root + volumes in a way that they can only be unlocked before the transition to the host system. Thus we have + two classes of secrets or credentials: one that can be unlocked during the entire runtime, and the + other that can only be used in the initrd. + + $ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-private.pem +.+........+.+........+.......+...+...+........+....+......+..+.......... +$ openssl rsa -pubout -in tpm2-pcr-private.pem -out tpm2-pcr-public.pem +$ openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out tpm2-pcr-initrd-private.pem +..+.......++........+........+......+........+....+.....+.+..+.......... +$ openssl rsa -pubout -in tpm2-pcr-initrd-private.pem -out tpm2-pcr-initrd-public.pem +# ukify --output vmlinux-1.2.3.efi \ + --os-release=@os-release.txt \ + --cmdline=@cmdline.txt \ + --splash=splash.bmp \ + --devicetree=devicetree.dtb \ + --pcr-private-key=tpm2-pcr-private.pem \ + --pcr-public-key=tpm2-pcr-public.pem \ + --phases=enter-initrd,enter-initrd:leave-initrd,enter-initrd:leave-initrd:sysinit,enter-initrd:leave-initrd:sysinit:ready \ + --pcr-banks=sha1,sha256 \ + --pcr-private-key=tpm2-pcr-initrd-private.pem \ + --pcr-public-key=tpm2-pcr-initrd-public.pem \ + --phases=enter-initrd \ + vmlinux-1.2.3 initrd.cpio \ + --uname=1.2.3 ++ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ +--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ +--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ +--private-key=tpm2-pcr-private.pem --public-key=tpm2-pcr-public.pem \ +--phase=enter-initrd --phase=enter-initrd:leave-initrd \ +--phase=enter-initrd:leave-initrd:sysinit \ +--phase=enter-initrd:leave-initrd:sysinit:ready ++ /usr/lib/systemd/systemd-measure sign --linux=vmlinux-1.2.3 \ +--osrel=os-release.txt --cmdline=cmdline.txt --dtb=devicetree.dtb \ +--splash=splash.bmp --initrd=initrd.cpio --bank=sha1 --bank=sha256 \ +--private-key=tpm2-pcr-initrd-private.pem \ +--public-key=tpm2-pcr-initrd-public.pem \ +--phase=enter-initrd +Wrote unsigned vmlinux-1.2.3.efi + + + ukify prints out both invocations of systemd-measure as + informative output (the lines starting with +); this allows us to see how + systemd-measure is called. It then merges the output of both invocations into the + .pcrsig section. systemd-measure may also do this merge itself + using the option. + + Note that in this example the .pcrpkey PE section contains the key specified + by the first option, covering all boot phases. The + .pcrpkey section is used in the default policies of + systemd-cryptenroll and systemd-creds. To use the stricter policy + bound to tpm-pcr-initrd-public.pem, specify on + the command line of those tools. + + + + + Exit status + + On success, 0 is returned, a non-zero failure code otherwise. + + + + See Also + + systemd1, + systemd-stub7, + ukify1, + systemd-creds1, + systemd-cryptsetup@.service8, + systemd-pcrphase.service8 + + + + -- cgit v1.2.3