From 048bcb9d1f813df344a4aaed31c5687856ecf6e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 12 Jan 2023 09:02:08 +0100 Subject: man: use ukify more in systemd-measure examples ukify supports signing with multiple keys, so show an example of this, and just let ukify print the calls to systemd-measure that will be done. This also does other small cleanups: - Use more realistic names in examples - Use $ as the prompt for commands that don't require root (most don't). Once we switch to operations that don't require a TPM, we should be able to get rid of the remaining calls that require root. - Ellipsize or linebreak various parts - Use --uname. We warn if it is not specified and we have to do autodetection, so let's nudge people towards including it rather than not. Follow-up for e069c57f0616d39363d36ac7f9c3e6ec8be01ab1. --- man/systemd-measure.xml | 159 +++++++++++++++++++++++++++--------------------- man/ukify.xml | 2 +- 2 files changed, 90 insertions(+), 71 deletions(-) (limited to 'man') diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml index 950aeebc54..0df3602223 100644 --- a/man/systemd-measure.xml +++ b/man/systemd-measure.xml @@ -33,16 +33,23 @@ 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 unified Linux kernel image based on + 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. + 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. @@ -209,26 +216,31 @@ Generate a unified kernel image, and calculate the expected TPM PCR 11 value - # ukify --output foo.efi \ - --os-release @os-release.txt \ - --cmdline @cmdline.txt \ - --splash splash.bmp \ - --devicetree devicetree.dtb \ + $ 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=1cf67dff4757e61e5a73d2a21a6694d668629bbc3761747d493f7f49ad720be02fd07263e1f93061243aec599d1ee4b4 -11:sha512=8e79acd3ddbbc8282e98091849c3530f996303c8ac8e87a3b2378b71c8b3a6e86d5c4f41ecea9e1517090c3e8ec0c714821032038f525f744960bcd082d937da +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, and a unified kernel image, and a TPM PCR 11 signature for + <title>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 + $ 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 \ @@ -241,25 +253,30 @@ --bank=sha256 \ --private-key=tpm2-pcr-private.pem \ --public-key=tpm2-pcr-public.pem >tpm2-pcr-signature.json -# ukify --output foo.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 \ +# 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 + # 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: - # /usr/lib/systemd/systemd-cryptsetup attach myvolume /dev/sda5 - tpm2-device=auto,tpm2-signature=/path/to/tpm2-pcr-signature.json + # /usr/lib/systemd/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 foo.efi is booted the + 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. @@ -274,53 +291,55 @@ 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 -# systemd-measure sign \ - --linux=vmlinux \ - --osrel=os-release.txt \ - --cmdline=cmdline.txt \ - --initrd=initrd.cpio \ + $ 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 \ - --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.tmp -# 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 -# 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-initrd-private.pem \ - --public-key=tpm2-pcr-initrd-public.pem \ - --phase=enter-initrd \ - --append=tpm2-pcr-signature.json.tmp >tpm2-pcr-signature.json -# ukify --output foo.efi \ - --os-release @os-release.txt \ - --cmdline @cmdline.txt \ - --splash splash.bmp \ - --devicetree devicetree.dtb \ - --pcr-private-key tpm2-pcr-initrd-private.pem \ - --pcr-public-key tpm2-pcr-initrd-public.pem \ - --section .pcrsig=@tpm2-pcr-signature.json \ - --section .pcrpkey=@tpm2-pcr-public.pem \ - vmlinux initrd.cpio + --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. - - Note that in this example the .pcrpkey PE section contains the key covering all - boot phases. The .pcrpkey is used in the default policies of - systemd-cryptenroll and systemd-creds. To use the stricter - tpm-pcr-initrd-public.pem-bound policy, specify - on the command line of those tools. diff --git a/man/ukify.xml b/man/ukify.xml index 97c3f899c7..c6bfbdc9d9 100644 --- a/man/ukify.xml +++ b/man/ukify.xml @@ -63,7 +63,7 @@ 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 + 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 -- cgit v1.2.1