docs: document the new smbios measurements

diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md
index 36380f38f3328eb9b140c42f1116cc1ad28802a5..efe5c1cce29fa8537b108c1ea8f1a056ce9ce566 100644 (file)
--- a/docs/BOOT_LOADER_INTERFACE.md
+++ b/docs/BOOT_LOADER_INTERFACE.md
@@ -145,6 +145,8 @@ Variables will be listed below using the Linux efivarfs naming,
   * `1 << 19` → The boot loader supports the `LoaderEntryPreferred` variable when set.
   * `1 << 20` → The boot loader reports the firmware-configured keyboard layout in the
                 EFI variable `LoaderKeyboardLayout-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
+  * `1 << 21` → The boot loader measures SMBIOS information into a TPM2 PCR and reports the PCR index in the
+                EFI variable `LoaderPcrSMBIOS-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`.
 
 * The EFI variable `LoaderSystemToken-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`
   contains binary random data,
@@ -184,6 +186,17 @@ Variables will be listed below using the Linux efivarfs naming,
   uses this as a lowest-priority fallback keyboard layout
   when no explicit configuration is provided.
 
+* The EFI variable `LoaderPcrSMBIOS-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`
+  contains the index of the TPM2 PCR (as a decimal ASCII string formatted as a
+  NUL-terminated UTF-16 string, e.g. `1`) into which the boot loader measured
+  select SMBIOS structures: type 1 (system information, with the volatile
+  "Wake-up Type" field zeroed out), type 2 (baseboard information) and type 11
+  (OEM strings). This is a volatile (non-persistent) variable, set only if a
+  measurement was successfully completed, and remains unset otherwise. Both
+  `systemd-boot` and `systemd-stub` perform this measurement; whichever runs
+  first sets the variable, and its presence suppresses a second measurement of
+  the same data into the same PCR during the same boot.
+
 If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze`
 will include them in its boot-time analysis.  If `LoaderDevicePartUUID` is set,
 systemd will mount the ESP that was used for the boot to `/boot`, but only if

diff --git a/docs/TPM2_PCR_MEASUREMENTS.md b/docs/TPM2_PCR_MEASUREMENTS.md
index 5d0801a9073ec1e8aa7555d4a45ec322df414cbc..8bdcd6979e3c8647ca0597f33500e483a6515c63 100644 (file)
--- a/docs/TPM2_PCR_MEASUREMENTS.md
+++ b/docs/TPM2_PCR_MEASUREMENTS.md
@@ -91,6 +91,45 @@ must be employed when designing a system that uses this feature.
 
 ## PCR Measurements Made by `systemd-boot` (UEFI)
 
+### PCR 1, `EV_EVENT_TAG`, SMBIOS information
+
+Select SMBIOS structures provided by the firmware are measured into PCR 1 (the
+TCG-defined register for platform configuration data), one tagged event per
+structure:
+
+* SMBIOS type 1 (system information). The volatile "Wake-up Type" field is
+  zeroed before measuring, since it varies depending on how the machine was
+  powered on (cold boot, resume from sleep, AC restore, …) and would otherwise
+  make the measurement non-reproducible.
+* SMBIOS type 2 (baseboard information).
+* SMBIOS type 11 (OEM strings). There may be more than one such structure; all
+  are measured.
+
+Note that these measurements are – strictly speaking – redundant, since
+firmwares are supposed to measure SMBIOS data anyway on their own. However, it
+has been found this is not the case on many real-life implementations. Since in
+particular SMBIOS type 11 may carry highly relevant input for the OS
+(e.g. system credentials), an explicit measurement is made here to ensure all
+parameters for the OS are comprehensively measured even on flaky firmwares.
+
+→ **Event Tag** `0xd5cb7cbc` for type 1, `0xe0d47bc8` for type 2, `0xc0b3bd23`
+for type 11.
+
+→ **Description** in the event log record is `smbios:type1`, `smbios:type2` or
+`smbios:type11` respectively, in UTF-16.
+
+→ **Measured hash** covers the raw bytes of the SMBIOS structure (formatted area
+plus trailing string set), with the type 1 "Wake-up Type" field zeroed out as
+described above.
+
+This measurement is also performed by `systemd-stub` (see below), so that systems
+that boot a UKI directly, bypassing `systemd-boot`, still get it. Whichever
+component runs first performs the measurement and sets the volatile
+`LoaderPcrSMBIOS` EFI variable to the PCR index used; its presence suppresses a
+second measurement of the same data into the same PCR during the same boot. Note
+that the firmware itself typically also extends PCR 1, so its final value is not
+solely determined by this measurement.
+
 ### PCR 5, `EV_EVENT_TAG`, `loader.conf`
 
 The content of `systemd-boot`'s configuration file, `loader/loader.conf`, is
@@ -120,6 +159,14 @@ trailing NUL bytes).
 
 ## PCR Measurements Made by `systemd-stub` (UEFI)
 
+### PCR 1, `EV_EVENT_TAG`, SMBIOS information
+
+Identical to the SMBIOS measurement described above for `systemd-boot`. When
+`systemd-stub` is invoked by `systemd-boot`, the measurement has typically already
+been made (tracked via the `LoaderPcrSMBIOS` EFI variable) and is not repeated;
+when the UKI is booted directly by the firmware, `systemd-stub` performs it
+itself.
+
 ### PCR 11, `EV_IPL`, PE section name
 
 A measurement is made for each PE section of the UKI that is defined by the