Add support for PCR predictions and measured boot

Add PCR-prediction nodes to allow storing expected TPM PCR values in
configurations, enabling TPM policy binding where secrets sealed to
expected PCR values can only be unsealed when the correct images are
loaded.

Use the existing signature-node structure to sign the PCR predictions
for remote attestation, and document the measured boot algorithm
specifying the order in which images are measured: kernel, ramdisk,
loadables, fdt (with overlays), and cmdline.

Co-developed-by: Claude <noreply@anthropic.com>
Signed-off-by: Simon Glass <simon.glass@canonical.com>

Author: sjg20

source/chapter2-source-file-format.rst

@@ -551,6 +551,10 @@ signature-1
     Each signature sub-node represents a separate signature
     calculated for the configuration according to specified algorithm.
 
+pcr-1
+    Each PCR-prediction sub-node represents an expected PCR value
+    for a particular TPM bank. See :ref:`pcr_prediction_nodes`.
+
 
 Configuration nodes
 -------------------
@@ -567,6 +571,7 @@ Each configuration has the following structure::
         |- script = "script sub-node unit-name";
         |- compatible = "vendor,board-style device tree compatible string";
         o signature-1 {...}
+        o pcr-1 {...}
 
 Mandatory properties
 ~~~~~~~~~~~~~~~~~~~~
@@ -691,5 +696,97 @@ padding
     if no value is provided we assume pkcs-1.5
 
 
+.. index:: PCR-prediction nodes
+
+.. _pcr_prediction_nodes:
+
+PCR-prediction nodes
+--------------------
+
+PCR-prediction nodes allow a FIT to include expected Platform Configuration
+Register (PCR) values.
+These values represent what the PCR should contain after the bootloader has
+measured the configuration's images into the TPM.
+This enables TPM policy binding,
+where secrets sealed to expected PCR values can only be unsealed when the
+correct images are loaded.
+
+::
+
+    o pcr-1
+        |- description = "PCR11 sha256 bank"
+        |- pcr = <11>;
+        |- algo = "sha256";
+        |- value = [expected PCR value]
+
+Mandatory properties
+~~~~~~~~~~~~~~~~~~~~
+
+pcr
+    The PCR index.
+    PCR 11 is conventionally used for kernel and related components.
+
+algo
+    Hash algorithm for this PCR bank.
+    Supported algorithms are:
+
+    =========== ============ ==========================================
+    Algorithm   Size (bytes) Meaning
+    =========== ============ ==========================================
+    sha256      32           Secure Hash Algorithm 2 (SHA256)
+    sha384      48           Secure Hash Algorithm 2 (SHA384)
+    sha512      64           Secure Hash Algorithm 2 (SHA512)
+    =========== ============ ==========================================
+
+value
+    Expected PCR value after all images have been measured.
+    This is computed by the signing tool based on the measurement algorithm
+    described in :ref:`measured_boot`.
+
+Optional properties
+~~~~~~~~~~~~~~~~~~~
+
+description
+    Textual description of this PCR prediction.
+
+Multiple PCR-prediction nodes may be present to support different TPM banks
+(e.g., both sha256 and sha384).
+
+Signing PCR predictions
+~~~~~~~~~~~~~~~~~~~~~~~
+
+PCR-prediction nodes can be signed using a standard configuration signature
+node to enable remote attestation and TPM policy binding.
+The signature covers the PCR-prediction node values,
+allowing a remote party to verify the expected measurements were produced by
+a trusted authority.
+
+To sign PCR predictions, include the PCR-prediction nodes in the signature's
+``hashed-nodes`` property::
+
+    o config-1
+        |- description = "Boot configuration with PCR predictions";
+        |- kernel = "kernel";
+        |- fdt = "fdt-1";
+        o pcr-1
+            |- pcr = <11>;
+            |- algo = "sha256";
+            |- value = [expected PCR value for sha256 bank]
+        o pcr-2
+            |- pcr = <11>;
+            |- algo = "sha384";
+            |- value = [expected PCR value for sha384 bank]
+        o signature-1
+            |- algo = "sha256,rsa2048";
+            |- key-name-hint = "pcr-policy-key";
+            |- hashed-nodes = "/configurations/config-1/pcr-1",
+                    "/configurations/config-1/pcr-2";
+            |- value = [signature value]
+
+In this example, the signature covers two PCR-prediction nodes for different
+TPM banks (sha256 and sha384),
+allowing a single signature to attest to all bank predictions.
+
+
 .. sectionauthor:: Marian Balakowicz <m8@semihalf.com>
 .. sectionauthor:: External data additions, 25/1/16 Simon Glass <sjg@chromium.org>

source/chapter3-usage.rst

@@ -252,4 +252,61 @@ For more information on FIT security, see
 The mechanism is also widely covered in conference talks, some of which are
 listed at `elinux.org <https://elinux.org/Boot_Loaders#U-Boot>`_.
 
+.. _measured_boot:
+
+Measured boot
+-------------
+
+FIT supports measured boot through integration with a Trusted Platform Module
+(TPM).
+When enabled, the bootloader extends a PCR with measurements of each image
+before loading it.
+This creates a cryptographic record of what was booted,
+enabling attestation and TPM-sealed secrets.
+
+Measurement algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+Images are measured in the following order:
+
+#. kernel or firmware
+#. ramdisk (if present)
+#. loadables (each image, in the order specified)
+#. fdt (each blob and overlay, in the order specified)
+#. cmdline (if present in the configuration)
+
+For each item, the measurement is performed as::
+
+    PCR = hash(PCR || hash(data))
+
+Where:
+
+- ``PCR`` is the current PCR value (initially all zeros if the PCR was reset)
+- ``hash`` is the TPM bank's hash algorithm (e.g., SHA-256)
+- ``data`` is the raw image data, after any decompression
+
+Only the image data is measured, not metadata such as load addresses,
+compression type, or image descriptions.
+For cmdline, the UTF-8 encoded string value is measured directly.
+
+The signing tool can pre-calculate expected PCR values using this algorithm.
+These values may be stored in PCR-prediction nodes within the configuration.
+
+TPM policy binding
+~~~~~~~~~~~~~~~~~~
+
+Expected PCR values enable TPM policy binding.
+Secrets can be sealed to a TPM policy that requires specific PCR values.
+The secrets can only be unsealed when the measured boot produces the expected
+PCR state.
+
+This is useful for:
+
+- Encrypting disk encryption keys that are only released to authorised images
+- Protecting credentials that should only be available to verified boot chains
+- Remote attestation, where a third party verifies the boot state
+
+For interoperability, PCR 11 is recommended for FIT image measurements,
+following the convention established by Unified Kernel Images (UKI).
+
 .. sectionauthor:: Simon Glass <sjg@chromium.org>