system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-21 18:24:38 +00:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity

man: update TPM2 PCR documentation

Browse source 
The assignments were partly simply incorrectly documented, partly changed
with 4d32507f51 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.
This commit is contained in:
Lennart Poettering 2022-04-14 14:38:52 +02:00 committed by Luca Boccassi
parent f4bdbae725
commit ebf3ee4105
2 changed files with 85 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
man/systemd-cryptenroll.xml
View file

@ -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>

80
man/systemd-stub.xml
View file

@ -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>