system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-22 18:55:10 +00:00
Code Issues Actions 7 Packages Projects Releases Wiki Activity

markdown: add document listing TPM2 PCR measurements we make comprehensively

Browse source 
This is useful to write TPM event log decoders.
This commit is contained in:
Lennart Poettering 2023-10-02 20:49:04 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 714cb48a4f
commit 4c376e58da
5 changed files with 170 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

162
docs/TPM2_PCR_MEASUREMENTS.md Normal file
View file

@ -0,0 +1,162 @@
---
title: TPM2 PCR Measurements Made by systemd
category: Booting
layout: default
SPDX-License-Identifier: LGPL-2.1-or-later
---
# TPM2 PCR Measurements Made by systemd
Various systemd components issue TPM2 PCR measurements during the boot process,
both in UEFI mode and from userspace. The following lists all measurements
done, and describes (in case done before `ExitBootServices()`) how they appear
in the TPM2 Event Log, maintained by the PC firmware. Note that the userspace
measurements listed below are (by default) only done if a system is booted with
`systemd-stub` — or in other words: systemd's userspace measurements are linked
to systemd's UEFI-mode measurements, and if the latter are not done the former
aren't made either.
systemd will measure to PCRs 11 (`kernel-boot`), 12 (`kernel-config`), 13
(`sysexts`), 15 (`system-identity`).
Currently, four components will issue TPM2 PCR measurements:
* The [`systemd-boot`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html) boot menu (UEFI)
* The [`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html) boot stub (UEFI)
* The [`systemd-pcrextend`](https://www.freedesktop.org/software/systemd/man/systemd-pcrphase.service.html) measurement tool (userspace)
* The [`systemd-cryptsetup`](https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup@.service.html) disk encryption tool (userspace)
A userspace measurement event log in a format close to TCG CEL-JSON is
maintained in `/run/log/systemd/tpm2-measure.log`.
## PCR Measurements Made by `systemd-boot` (UEFI)
### PCR 12, `EV_IPL`, "Kernel Command Line"
If the kernel command line was specified explicitly (by the user or in a Boot
Loader Specification Type #1 file), the kernel command line passed to the
invoked kernel is measured before it is executed. (In case an UKI/Boot Loader
Specification Type #2 entry is booted, the built-in kernel command line is
implicitly measured as part of the PE sections, because it is embedded in the
`.cmdline` PE section, hence doesn't need to be measured by `systemd-boot`; see
below for details on PE section measurements done by `systemd-stub`.)
→ **Description** in the event log record is the literal kernel command line in
UTF-16.
→ **Measured hash** covers the literal kernel command line in UTF-16 (without any
trailing NUL bytes).
## PCR Measurements Made by `systemd-stub` (UEFI)
### PCR 11, `EV_IPL`, "PE Section Name"
A measurement is made for each PE section of the UKI that is defined by the
[UKI
specification](https://uapi-group.org/specifications/specs/unified_kernel_image/),
in the canonical order described in the specification.
Happens once for each UKI-defined PE section of the UKI, in the canonical UKI
PE section order, as per the UKI specification. For each record a pair of
records is written, first one that covers the PE section name (described here),
and the second one that covers the PE section data (described below), so that
both types of records appear interleaved in the event log.
→ **Description** in the event log record is the PE section name in UTF-16.
→ **Measured hash** covers the PE section name in ASCII (*including* a trailing NUL byte!).
### PCR 11, `EV_IPL`, "PE Section Data"
Happens once for each UKI-defined PE section of the UKI, in the canonical UKI
PE section order, as per the UKI specification, see above.
→ **Description** in the event log record is the PE section name in UTF-16.
→ **Measured hash** covers the (binary) PE section contents.
### PCR 12, `EV_IPL`, "Kernel Command Line"
Might happen up to four times, for kernel command lines from:
1. Passed cmdline
2. System cmdline add-ons (one measurement covering all add-ons combined)
3. Per-UKI cmdline add-ons (one measurement covering all add-ons combined)
2. SMBIOS cmdline
→ **Description** in the event log record is the literal kernel command line in
UTF-16.
→ **Measured hash** covers the literal kernel command line in UTF-16 (without any
trailing NUL bytes).
### PCR 12, `EV_IPL`, "Per-UKI Credentials initrd"
→ **Description** in the event log record is the constant string "Credentials
initrd" in UTF-16.
→ **Measured hash** covers the per-UKI credentials cpio archive (which is generated
on-the-fly by `systemd-stub`).
### PCR 12, `EV_IPL`, "Global Credentials initrd"
→ **Description** in the event log record is the constant string "Global
credentials initrd" in UTF-16.
→ **Measured hash** covers the global credentials cpio archive (which is generated
on-the-fly by `systemd-stub`).
### PCR 13, `EV_IPL`, "sysext initrd"
→ **Description** in the event log record is the constant string "System extension
initrd" in UTF-16.
→ **Measured hash** covers the per-UKI sysext cpio archive (which is generated
on-the-fly by `systemd-stub`).
## PCR Measurements Made by `systemd-pcrextend` (Userspace)
### PCR 11, "Boot Phases"
The `systemd-pcrphase.service`, `systemd-pcrphase-initrd.service`,
`systemd-pcrphase-sysinit.service` services will measure the boot phase reached
during various times of the boot process. Specifically, the strings
"enter-initrd", "leave-initrd", "sysinit", "ready", "shutdown", "final" are
measured, in this order. (These are regular units, and administrators may
choose to define additional/different phases.)
→ **Measured hash** covers the phase string (in UTF-8, without trailing NUL
bytes).
### PCR 15, "Machine ID"
The `systemd-pcrmachine.service` service will measure the machine ID (as read
from `/etc/machine-id`) during boot.
→ **Measured hash** covers the string "machine-id:" suffixed by the machine ID
formatted in hexadecimal lowercase characters (in UTF-8, without trailing NUL
bytes).
### PCR 15, "File System"
The `systemd-pcrfs-root.service` and `systemd-pcrfs@.service` services will
measure a string identifying a specific file system, typically covering the
root file system and `/var/` (if it is its own file system).
→ **Measured hash** covers the string "file-system:" suffixed by a series of six
colon-separated strings, identifying the file system type, UUID, label as well
as the GPT partition entry UUID, entry type UUID and entry label (in UTF-8,
without trailing NUL bytes).
## PCR Measurements Made by `systemd-cryptsetup` (Userspace)
### PCR 15, "Volume Key"
The `systemd-cryptsetup@.service` service will measure a key derived from the
LUKS volume key of a specific encrypted volume, typically covering the backing
encryption device of the root file system and `/var/` (if it is its own file
system).
→ **Measured hash** covers the (binary) result of the HMAC(V,S) calculation where V
is the LUKS volume key, and S is the string "cryptsetup:" followed by the LUKS
volume name and the UUID of the LUKS superblock.

3
man/systemd-boot.xml
View file

@ -612,7 +612,8 @@
<citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>,
<ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
<ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
<ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink>
</para>
</refsect1>
</refentry>

3
man/systemd-cryptsetup.xml
View file

@ -111,7 +111,8 @@
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry project='die-net'><refentrytitle>cryptsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink>
</para>
</refsect1>

3
man/systemd-pcrphase.service.xml
View file

@ -237,7 +237,8 @@
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink>
</para>
</refsect1>

3
man/systemd-stub.xml
View file

@ -485,7 +485,8 @@
<ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>,
<ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
<citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>
<citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink>
</para>
</refsect1>
</refentry>