From: Lennart Poettering Date: Thu, 14 Apr 2022 12:38:52 +0000 (+0200) Subject: man: update TPM2 PCR documentation X-Git-Tag: v251-rc2~92 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ebf3ee410536d9f9a1cab513538fdbc596c47908;p=thirdparty%2Fsystemd.git man: update TPM2 PCR documentation The assignments were partly simply incorrectly documented, partly changed with 4d32507f5186a89e98093659fbbe386787a97b9f and partly missing. Moreover kernel 5.17 now measures all initrds to PCR 9 on its own (https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df) Let's correct all this and bring it up-to-date. And while we are at it extend the docs about this in systemd-stub, with a new table that indicates which OS resource is protected by which PCR. --- diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index 3b235fd9c93..6616d8bdb9f 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -251,7 +251,7 @@ 4 - Boot loader; changes on boot loader updates. The shim project will measure the PE binary it chain loads into this PCR. + Boot loader and additional drivers; changes on boot loader updates. The shim project will measure the PE binary it chain loads into this PCR. If the Linux kernel is invoked as UEFI PE binary, it is measured here, too. sd-stub7 measures system extension images read from the ESP here too (see systemd-sysext8). @@ -273,8 +273,9 @@ - 12 - sd-boot7 measures the kernel command line into this PCR. + 9 + The Linux kernel measures all initial RAM file systems it receives into this PCR. + @@ -282,6 +283,11 @@ The IMA project measures its runtime state into this PCR. + + 12 + systemd-boot7 measures any specified kernel command line into this PCR. systemd-stub7 measures any manually specified kernel command line (i.e. a kernel command line that overrides the one embedded in the unified PE image) and loaded credentials into this PCR. (Note that if sytemd-boot and systemd-stub are used in combination the command line might be measured twice!) + + 14 The shim project measures its "MOK" certificates and hashes into this PCR. diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 3a8fc925d7f..d00c8ac66cc 100644 --- a/man/systemd-stub.xml +++ b/man/systemd-stub.xml @@ -70,7 +70,7 @@ image, any attempts to override the kernel command line by passing one as invocation parameters to the EFI binary are ignored. Thus, in order to allow overriding the kernel command line, either disable UEFI SecureBoot, or don't include a kernel command line PE section in the kernel image file. If a command line - is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 8 (if a TPM is + is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 12 (if a TPM is present). If a DeviceTree is embedded in the .dtb section, it replaces an existing @@ -100,7 +100,7 @@ systemd-creds1 for details on encrypted credentials. The generated cpio archive is measured into TPM - PCR 4 (if a TPM is present). + PCR 12 (if a TPM is present). Similarly, files foo.efi.extra.d/*.raw are packed up in a cpio archive and placed in the /.extra/sysext/ @@ -108,13 +108,13 @@ images to the initrd. See systemd-sysext8 for details on system extension images. The generated cpio archive containing these - system extension images is measured into TPM PCR 8 (if a TPM is present). + system extension images is measured into TPM PCR 4 (if a TPM is present). Files /loader/credentials/*.cred are packed up in a cpio archive and placed in the /.extra/global_credentials/ directory of the initrd file hierarchy. This is supposed to be used to pass additional credentials to the initrd, regardless of the kernel being booted. The generated cpio archive is - measured into TPM PCR 4 (if a TPM is present) + measured into TPM PCR 12 (if a TPM is present) These mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd @@ -125,6 +125,78 @@ details); in case of the system extension images by using signed Verity images. + + TPM2 PCR Notes + + Note that when a unified kernel using systemd-stub is invoked the firmware will + measure it as a whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the + core kernel, the embedded initrd and kernel command line (see above for a full list). + + Also note that the Linux kernel will measure all initrds it receives into TPM PCR 9. This means + every type of initrd will be measured twice: the initrd embedded in the kernel image will be measured to + both PCR 4 and PCR 9; the initrd synthesized from credentials will be measured to both PCR 12 and PCR 9; + the initrd synthesized from system extensions will be measured to both PCR 4 and PCR 9. Let's summarize + the OS resources and the PCRs they are measured to: + + + OS Resource PCR Summary + + + + + + + + OS Resource + Measurement PCR + + + + + + systemd-stub code (the entry point of the unified PE binary) + 4 + + + + Boot splash (embedded in the unified PE binary) + 4 + + + + Core kernel code (embedded in unified PE binary) + 4 + + + + Main initrd (embedded in unified PE binary) + 4 + 9 + + + + Default kernel command line (embedded in unified PE binary) + 4 + + + + Overriden kernel command line + 12 + + + + Credentials (synthesized initrd from companion files) + 12 + 9 + + + + System Extensions (synthesized initrd from companion files) + 4 + 9 + + + +
+ + EFI Variables