diff options
| -rw-r--r-- | man/systemd-cryptenroll.xml | 12 | ||||
| -rw-r--r-- | man/systemd-stub.xml | 80 |
2 files changed, 85 insertions, 7 deletions
diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index 3b235fd9c9..6616d8bdb9 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -251,7 +251,7 @@ <row> <entry>4</entry> - <entry>Boot loader; changes on boot loader updates. The shim project will measure the PE binary it chain loads into this PCR.</entry> + <entry>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. <citerefentry><refentrytitle>sd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures system extension images read from the ESP here too (see <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>).</entry> </row> <row> @@ -273,8 +273,9 @@ <!-- Grub measures all files it reads (including kernel image, initrd, …) into PCR 9… --> <row> - <entry>12</entry> - <entry><citerefentry><refentrytitle>sd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures the kernel command line into this PCR.</entry> + <entry>9</entry> + <entry>The Linux kernel measures all initial RAM file systems it receives into this PCR.</entry> + <!-- Strictly speaking only Linux >= 5.17 using the LOAD_FILE2 protocol, see https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f046fff8bc4c4d8f8a478022e76e40b818f692df --> </row> <row> @@ -283,6 +284,11 @@ </row> <row> + <entry>12</entry> + <entry><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> measures any specified kernel command line into this PCR. <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> 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 <command>sytemd-boot</command> and <command>systemd-stub</command> are used in combination the command line might be measured twice!)</entry> + </row> + + <row> <entry>14</entry> <entry>The shim project measures its "MOK" certificates and hashes into this PCR.</entry> </row> diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml index 3a8fc925d7..d00c8ac66c 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).</para> <para>If a DeviceTree is embedded in the <literal>.dtb</literal> section, it replaces an existing @@ -100,7 +100,7 @@ <citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry> for details on encrypted credentials. The generated <command>cpio</command> archive is measured into TPM - PCR 4 (if a TPM is present).</para></listitem> + PCR 12 (if a TPM is present).</para></listitem> <listitem><para>Similarly, files <filename><replaceable>foo</replaceable>.efi.extra.d/*.raw</filename> are packed up in a <command>cpio</command> archive and placed in the <filename>/.extra/sysext/</filename> @@ -108,13 +108,13 @@ images to the initrd. See <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details on system extension images. The generated <command>cpio</command> archive containing these - system extension images is measured into TPM PCR 8 (if a TPM is present).</para></listitem> + system extension images is measured into TPM PCR 4 (if a TPM is present).</para></listitem> <listitem><para>Files <filename>/loader/credentials/*.cred</filename> are packed up in a <command>cpio</command> archive and placed in the <filename>/.extra/global_credentials/</filename> 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 <command>cpio</command> archive is - measured into TPM PCR 4 (if a TPM is present)</para></listitem> + measured into TPM PCR 12 (if a TPM is present)</para></listitem> </itemizedlist> <para>These mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd @@ -126,6 +126,78 @@ </refsect1> <refsect1> + <title>TPM2 PCR Notes</title> + + <para>Note that when a unified kernel using <command>systemd-stub</command> 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).</para> + + <para>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:</para> + + <table> + <title>OS Resource PCR Summary</title> + + <tgroup cols='2' align='left' colsep='1' rowsep='1'> + <colspec colname="pcr" /> + <colspec colname="definition" /> + + <thead> + <row> + <entry>OS Resource</entry> + <entry>Measurement PCR</entry> + </row> + </thead> + + <tbody> + <row> + <entry><command>systemd-stub</command> code (the entry point of the unified PE binary)</entry> + <entry>4</entry> + </row> + + <row> + <entry>Boot splash (embedded in the unified PE binary)</entry> + <entry>4</entry> + </row> + + <row> + <entry>Core kernel code (embedded in unified PE binary)</entry> + <entry>4</entry> + </row> + + <row> + <entry>Main initrd (embedded in unified PE binary)</entry> + <entry>4 + 9</entry> + </row> + + <row> + <entry>Default kernel command line (embedded in unified PE binary)</entry> + <entry>4</entry> + </row> + + <row> + <entry>Overriden kernel command line</entry> + <entry>12</entry> + </row> + + <row> + <entry>Credentials (synthesized initrd from companion files)</entry> + <entry>12 + 9</entry> + </row> + + <row> + <entry>System Extensions (synthesized initrd from companion files)</entry> + <entry>4 + 9</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> <title>EFI Variables</title> <para>The following EFI variables are defined, set and read by <command>systemd-stub</command>, under the |