docs/TPM2_PCR_MEASUREMENTS.md

   1 ---
   2 title: TPM2 PCR Measurements Made by systemd
   3 category: Booting
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # TPM2 PCR Measurements Made by systemd
   9
  10 Various systemd components issue TPM2 PCR measurements during the boot process,
  11 both in UEFI mode and from userspace. The following lists all measurements
  12 done, and describes (in case done before `ExitBootServices()`) how they appear
  13 in the TPM2 Event Log, maintained by the PC firmware. Note that the userspace
  14 measurements listed below are (by default) only done if a system is booted with
  15 `systemd-stub` — or in other words: systemd's userspace measurements are linked
  16 to systemd's UEFI-mode measurements, and if the latter are not done the former
  17 aren't made either.
  18
  19 systemd will measure to PCRs 5 (`boot-loader-config`), 11 (`kernel-boot`),
  20 12 (`kernel-config`), 13 (`sysexts`), 15 (`system-identity`).
  21
  22 Currently, four components will issue TPM2 PCR measurements:
  23
  24 * The [`systemd-boot`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html) boot menu (UEFI)
  25 * The [`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html) boot stub (UEFI)
  26 * The [`systemd-pcrextend`](https://www.freedesktop.org/software/systemd/man/systemd-pcrphase.service.html) measurement tool (userspace)
  27 * The [`systemd-cryptsetup`](https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup@.service.html) disk encryption tool (userspace)
  28
  29 A userspace measurement event log in a format close to TCG CEL-JSON is
  30 maintained in `/run/log/systemd/tpm2-measure.log`.
  31
  32 ## Measurements Added in Future
  33
  34 We expect that we'll add further PCR extensions in future (both in firmware and
  35 user mode), which also will be documented here. When executed from firmware
  36 mode future additions are expected to be recorded as `EV_EVENT_TAG`
  37 measurements in the event log, in order to make them robustly
  38 recognizable. Measurements currently recorded as `EV_IPL` will continue to be
  39 recorded as `EV_IPL`, for compatibility reasons. However, `EV_IPL` will not be
  40 used for new, additional measurements.
  41
  42 ## PCR Measurements Made by `systemd-boot` (UEFI)
  43
  44 ### PCS 5, `EV_EVENT_TAG`, "loader.conf"
  45
  46 The content of `systemd-boot`'s configuration file, `loader/loader.conf`, is
  47 measured as a tagged event.
  48
  49 → **Event Tag** `0xf5bc582a`
  50
  51 → **Description** in the event log record is the file name, `loader.conf`.
  52
  53 → **Measured hash** covers the content of `loader.conf` as it is read from the ESP.
  54
  55 ### PCR 12, `EV_IPL`, "Kernel Command Line"
  56
  57 If the kernel command line was specified explicitly (by the user or in a Boot
  58 Loader Specification Type #1 file), the kernel command line passed to the
  59 invoked kernel is measured before it is executed. (In case an UKI/Boot Loader
  60 Specification Type #2 entry is booted, the built-in kernel command line is
  61 implicitly measured as part of the PE sections, because it is embedded in the
  62 `.cmdline` PE section, hence doesn't need to be measured by `systemd-boot`; see
  63 below for details on PE section measurements done by `systemd-stub`.)
  64
  65 → **Description** in the event log record is the literal kernel command line in
  66 UTF-16.
  67
  68 → **Measured hash** covers the literal kernel command line in UTF-16 (without any
  69 trailing NUL bytes).
  70
  71 ## PCR Measurements Made by `systemd-stub` (UEFI)
  72
  73 ### PCR 11, `EV_IPL`, "PE Section Name"
  74
  75 A measurement is made for each PE section of the UKI that is defined by the
  76 [UKI
  77 specification](https://uapi-group.org/specifications/specs/unified_kernel_image/),
  78 in the canonical order described in the specification.
  79
  80 Happens once for each UKI-defined PE section of the UKI, in the canonical UKI
  81 PE section order, as per the UKI specification. For each record a pair of
  82 records is written, first one that covers the PE section name (described here),
  83 and the second one that covers the PE section data (described below), so that
  84 both types of records appear interleaved in the event log.
  85
  86 → **Description** in the event log record is the PE section name in UTF-16.
  87
  88 → **Measured hash** covers the PE section name in ASCII (*including* a trailing NUL byte!).
  89
  90 ### PCR 11, `EV_IPL`, "PE Section Data"
  91
  92 Happens once for each UKI-defined PE section of the UKI, in the canonical UKI
  93 PE section order, as per the UKI specification, see above.
  94
  95 → **Description** in the event log record is the PE section name in UTF-16.
  96
  97 → **Measured hash** covers the (binary) PE section contents.
  98
  99 ### PCR 12, `EV_IPL`, "Kernel Command Line"
 100
 101 Might happen up to three times, for kernel command lines from:
 102
 103  1. Passed cmdline
 104  2. System and per-UKI cmdline add-ons (one measurement covering all add-ons combined)
 105  3. SMBIOS cmdline
 106
 107 → **Description** in the event log record is the literal kernel command line in
 108 UTF-16.
 109
 110 → **Measured hash** covers the literal kernel command line in UTF-16 (without any
 111 trailing NUL bytes).
 112
 113 ### PCR 12, `EV_EVENT_TAG`, "Devicetrees"
 114
 115 Devicetree addons are measured individually as a tagged event.
 116
 117 → **Event Tag** `0x6c46f751`
 118
 119 → **Description** the addon filename.
 120
 121 → **Measured hash** covers the content of the Devicetree.
 122
 123 ### PCR 12, `EV_IPL`, "Per-UKI Credentials initrd"
 124
 125 → **Description** in the event log record is the constant string "Credentials
 126 initrd" in UTF-16.
 127
 128 → **Measured hash** covers the per-UKI credentials cpio archive (which is generated
 129  on-the-fly by `systemd-stub`).
 130
 131 ### PCR 12, `EV_IPL`, "Global Credentials initrd"
 132
 133 → **Description** in the event log record is the constant string "Global
 134 credentials initrd" in UTF-16.
 135
 136 → **Measured hash** covers the global credentials cpio archive (which is generated
 137 on-the-fly by `systemd-stub`).
 138
 139 ### PCR 13, `EV_IPL`, "sysext initrd"
 140
 141 → **Description** in the event log record is the constant string "System extension
 142 initrd" in UTF-16.
 143
 144 → **Measured hash** covers the per-UKI sysext cpio archive (which is generated
 145 on-the-fly by `systemd-stub`).
 146
 147 ## PCR Measurements Made by `systemd-pcrextend` (Userspace)
 148
 149 ### PCR 11, "Boot Phases"
 150
 151 The `systemd-pcrphase.service`, `systemd-pcrphase-initrd.service`,
 152 `systemd-pcrphase-sysinit.service` services will measure the boot phase reached
 153 during various times of the boot process. Specifically, the strings
 154 "enter-initrd", "leave-initrd", "sysinit", "ready", "shutdown", "final" are
 155 measured, in this order. (These are regular units, and administrators may
 156 choose to define additional/different phases.)
 157
 158 → **Measured hash** covers the phase string (in UTF-8, without trailing NUL
 159 bytes).
 160
 161 ### PCR 15, "Machine ID"
 162
 163 The `systemd-pcrmachine.service` service will measure the machine ID (as read
 164 from `/etc/machine-id`) during boot.
 165
 166 → **Measured hash** covers the string "machine-id:" suffixed by the machine ID
 167 formatted in hexadecimal lowercase characters (in UTF-8, without trailing NUL
 168 bytes).
 169
 170 ### PCR 15, "File System"
 171
 172 The `systemd-pcrfs-root.service` and `systemd-pcrfs@.service` services will
 173 measure a string identifying a specific file system, typically covering the
 174 root file system and `/var/` (if it is its own file system).
 175
 176 → **Measured hash** covers the string "file-system:" suffixed by a series of six
 177 colon-separated strings, identifying the file system type, UUID, label as well
 178 as the GPT partition entry UUID, entry type UUID and entry label (in UTF-8,
 179 without trailing NUL bytes).
 180
 181 ## PCR Measurements Made by `systemd-cryptsetup` (Userspace)
 182
 183 ### PCR 15, "Volume Key"
 184
 185 The `systemd-cryptsetup@.service` service will measure a key derived from the
 186 LUKS volume key of a specific encrypted volume, typically covering the backing
 187 encryption device of the root file system and `/var/` (if it is its own file
 188 system).
 189
 190 → **Measured hash** covers the (binary) result of the HMAC(V,S) calculation where V
 191 is the LUKS volume key, and S is the string "cryptsetup:" followed by the LUKS
 192 volume name and the UUID of the LUKS superblock.