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 3b235fd9c93e637d7cefb43b699d98d492688d9a..6616d8bdb9f2476cd037d3531adf6b3401294dae 100644 (file)
--- 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>
@@ -282,6 +283,11 @@
                 <entry>The IMA project measures its runtime state into this PCR.</entry>
               </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>

diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml
index 3a8fc925d7f190f848569ec909551c722f388f6d..d00c8ac66cc16419ccec9cf2f815b309f7f17d57 100644 (file)
--- 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
@@ -125,6 +125,78 @@
     details); in case of the system extension images by using signed Verity images.</para>
   </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>