diff --git a/man/systemd-measure.xml b/man/systemd-measure.xml index 0fc0d0e87d..69ac348184 100644 --- a/man/systemd-measure.xml +++ b/man/systemd-measure.xml @@ -37,12 +37,12 @@ systemd-stub7 is booted up. It accepts paths to the ELF kernel image file, initial ram disk image file, devicetree file, kernel command line file, - os-release5 file, and - boot splash 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. + 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. @@ -66,9 +66,9 @@ 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.) + , , see below. Only + is mandatory. (Alternatively, specify to use the + current values of PCR register 11 instead.) @@ -104,6 +104,7 @@ + When used with the calculate or sign verb, configures the files to read the unified kernel image components from. Each option corresponds with @@ -135,7 +136,14 @@ These switches take paths to a pair of PEM encoded RSA key files, for use with - the sign command. + 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. @@ -185,19 +193,11 @@ - Generate a private/public key pair, and a unified kernel image, and a TPM PCR 11 signature for it + Generate a private/public key pair, and 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 -# objcopy \ - --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \ - --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \ - --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \ - --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \ - --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \ - --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \ - /usr/lib/systemd/boot/efi/linuxx64.efi.stub \ - foo.efi # systemd-measure sign \ --linux=vmlinux \ --osrel=os-release.txt \ @@ -205,10 +205,22 @@ --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 + --public-key=tpm2-pcr-public.pem > tpm2-pcr-signature.json +# objcopy \ + --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \ + --add-section .osrel=os-release.txt --change-section-vma .osrel=0x20000 \ + --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \ + --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \ + --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \ + --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \ + --add-section .pcrsig=tpm2-pcr-signature.json --change-section-vma .splash=0x80000 \ + --add-section .pcrpkey=tpm2-pcr-public.pem --change-section-vma .splash=0x90000 \ + /usr/lib/systemd/boot/efi/linuxx64.efi.stub \ + foo.efi Later on, enroll the signed PCR policy on a LUKS volume: @@ -217,6 +229,11 @@ 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 + + Note that when the generated unified kernel image foo.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. diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 1e9bb5d631..2479d9f5fa 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -68,6 +68,14 @@ A boot splash (in Windows .BMP format) to show on screen before invoking the kernel will be looked for in the .splash PE section. + + A set of cryptographic signatures for expected TPM2 PCR values when this kernel is + booted, in JSON format, in the .pcrsig section. This is useful for implementing TPM2 + policies that bind disk encryption and similar to kernels that are signed by a specific + key. + + A public key in PEM format matching this TPM2 PCR signature data in the + .pcrpkey section. If UEFI SecureBoot is enabled and the .cmdline section is present in the executed @@ -81,8 +89,25 @@ DeviceTree in the corresponding EFI configuration table. systemd-stub will ask the firmware via the EFI_DT_FIXUP_PROTOCOL for hardware specific fixups to the DeviceTree. - The contents of these six PE sections are measured into TPM PCR 11, that is otherwise not - used. Thus, it can be pre-calculated without too much effort. + The contents of seven of these eight PE sections are measured into TPM PCR 11, that is otherwise + not used. Thus, it can be pre-calculated without too much effort. The .pcrsig section + is not included in this PCR measurement, since it's supposed to contain signatures for the expected + results for these measurements, i.e. of the outputs of the measurement operation, and thus cannot also be + input to it. + + When .pcrsig and/or .pcrpkey are present in a unified kernel + image their contents are passed to the booted kernel in an synthetic initrd cpio archive that places them in the + /.extra/tpm2-pcr-signature.json and + /.extra/tpm2-pcr-public-key.pem files. Typically, a + tmpfiles.d5 line then + ensures they are copied into /run/systemd/tpm2-pcr-signature.json and + /run/systemd/tpm2-pcr-public-key.pem where they remain accessible even after the + system transitions out of the initrd environment into the host file system. Tools such + systemd-cryptsetup@.service8, + systemd-cryptenroll1 + and systemd-creds1 + will automatically use files present under these paths to unlock protected resources (encrypted storage + or credentials) or bind encryption to booted kernels. @@ -166,12 +191,12 @@ - Boot splash (embedded in the unified PE binary) + Core kernel code (embedded in unified PE binary) 4 + 11 - Core kernel code (embedded in unified PE binary) + OS release information (embedded in the unified PE binary) 4 + 11 @@ -190,6 +215,21 @@ 12 + + Boot splash (embedded in the unified PE binary) + 4 + 11 + + + + TPM2 PCR signature JSON (embedded in unified PE binary, synthesized into initrd) + 4 + 9 + + + + TPM2 PCR PEM public key (embedded in unified PE binary, synthesized into initrd) + 4 + 9 + 11 + + Credentials (synthesized initrd from companion files) 9 + 12 @@ -279,6 +319,66 @@ url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface. + + initrd Resources + + The following resources are passed as initrd cpio archives to the booted kernel, and thus make up + the initial file system hierarchy in the initrd execution environment: + + + + / + + The main initrd from the .initrd PE section of the unified kernel image. + + + + /.extra/credentials/*.cred + Credential files (suffix .cred) that are placed next to the + unified kernel image (as described above) are copied into the + /.extra/credentials/ directory in the initrd execution + environment. + + + + /.extra/global_credentials/*.cred + Similar, credential files in the /loader/credentials/ directory + in the file system the unified kernel image is placed in are copied into the + /.extra/global_credentials/ directory in the initrd execution + environment. + + + + /.extra/sysext/*.raw + System extension image files (suffix .raw) that are placed next to + the unified kernel image (as described above) are copied into the + /.extra/sysext/ directory in the initrd execution environment. + + + + /.extra/tpm2-pcr-signature.json + The TPM2 PCR signature JSON object included in the .pcrsig PE + section of the unified kernel image is copied into the + /.extra/tpm2-pcr-signature.json file in the initrd execution + environment. + + + + /.extra/tpm2-pcr-pkey.pem + The PEM public key included in the .pcrpkey PE section of the + unified kernel image is copied into the /.extra/tpm2-pcr-public-key.pem file in + the initrd execution environment. + + + + Note that all these files are located in the tmpfs file system the kernel sets + up for the initrd file hierarchy and are thus lost when the system transitions from the initrd execution + environment into the host file system. If these resources shall be kept around over this transition they + need to be copied to a place that survives the transition first, for example via a suitable + tmpfiles.d5 line. By + default, this is done for the TPM2 PCR signature and public key files. + + Assembling Kernel Images @@ -313,6 +413,10 @@ This expects a pair of X.509 private key and certificate as parameters and then signs the UEFI PE executable we generated above for UEFI SecureBoot and generates a signed UEFI PE executable as result. + + See + systemd-measure1 for + an example involving the .pcrsig and .pcrpkey sections. @@ -325,7 +429,8 @@ Boot Loader Specification, Boot Loader Interface, objcopy1, - sbsign1 + sbsign1, + systemd-measure1