1Measured Boot Design 2==================== 3 4This document briefly explains the Measured-Boot design implementation 5in |TF-A|. 6 7Introduction 8------------ 9 10Measured Boot is the process of computing and securely recording hashes of code 11and critical data at each stage in the boot chain before the code/data is used. 12 13These measurements can be leveraged by other components in the system to 14implement a complete attestation system. For example, they could be used to 15enforce local attestation policies (such as releasing certain platform keys or 16not), or they could be securely sent to a remote challenger a.k.a. `verifier` 17after boot to attest to the state of the code and critical-data. 18 19Measured Boot does not authenticate the code or critical-data, but simply 20records what code/critical-data was present on the system during boot. 21 22It is assumed that BL1 is implicitly trusted (by virtue of immutability) and 23acts as the root of trust for measurement hence it is not measured. 24 25The Measured Boot implementation in TF-A supports multiple backends to securely 26store measurements mentioned below in the :ref:`Measured Boot Backends` section. 27 28Critical data 29------------- 30 31All firmware images - i.e. BLx images and their corresponding configuration 32files, if any - must be measured. In addition to that, there might be specific 33pieces of data which needs to be measured as well. These are typically different 34on each platform. They are referred to as *critical data*. 35 36Critical data for the platform can be determined using the following criteria: 37 38#. Data that influence boot flow behaviour such as - 39 40 - Configuration parameters that alter the boot flow path. 41 - Parameters that determine which firmware to load from NV-Storage to 42 SRAM/DRAM to pass the boot process successfully. 43 44#. Hardware configurations settings, debug settings and security policies 45 that need to be in a valid state for a device to maintain its security 46 posture during boot and runtime. 47#. Security-sensitive data that is being updated by hardware. 48 49Examples of Critical data: 50 51#. The list of errata workarounds being applied at reset. 52#. State of fuses such as whether an SoC is in secure mode. 53#. NV counters that determine whether firmware is up-to-date and secure. 54 55Measurement slot 56---------------- 57 58The measurement slot resides in a Trusted Module and can be either a secure 59register or memory. 60The measurement slot is used to provide a method to cryptographically record 61(measure) images and critical data on a platform. 62The measurement slot update calculation, called an **extend** operation, is 63a one-way hash of all the previous measurements and the new measurement. It 64is the only way to change the slot value, thus no measurements can ever be 65removed or overwritten. 66 67.. _Measured Boot Backends: 68 69Measured Boot Backends 70---------------------- 71 72The Measured Boot implementation in TF-A supports: 73 74#. Event Log 75 76 The TCG Event Log holds a record of measurements made into the Measurement 77 Slot aka PCR (Platform Configuration Register). 78 79 The `TCG EFI Protocol Specification`_ provides details on how to measure 80 components. The Arm document 81 `Arm® Server Base Security Guide`_ provides specific guidance for 82 measurements on an SBSA/SBBR server system. By considering these 83 specifications it is decided that - 84 85 #. Use PCR0 for images measurements. 86 #. Use PCR1 for Critical data measurements. 87 88 TCG has specified the architecture for the structure of this log in the 89 `TCG EFI Protocol Specification`_. The specification describes two event 90 log event records—the legacy, fixed size SHA1 structure called TCG_PCR_EVENT 91 and the variable length crypto agile structure called TCG_PCR_EVENT2. Event 92 Log driver implemented in TF-A covers later part. 93 94#. Discrete TPM 95 96 A Discrete TPM (Trusted Platform Module) can be used alongside Event Log to 97 extend measurements and validate Measured Boot functionality. The use of a 98 Discrete TPM in TF-A to extend measurements of images and other critical data 99 allows for an additional layer of security. The TPM can be used to attest the 100 integrity of the Event Log. 101 102#. |RSE| 103 104 It is one of the physical backends to extend the measurements. Please refer 105 this document :ref:`Runtime Security Engine (RSE)` for more details. 106 107Platform Interface 108------------------ 109 110Every image which gets successfully loaded in memory (and authenticated, if 111trusted boot is enabled) then gets measured. In addition to that, platforms 112can measure any relevant piece of critical data at any point during the boot. 113The following diagram outlines the call sequence for Measured Boot platform 114interfaces invoked from generic code: 115 116.. image:: ../resources/diagrams/measured_boot_design.png 117 118These platform interfaces are used by BL1 and BL2 only, and are declared in 119``include/plat/common/platform.h``. 120BL31 does not load and thus does not measure any image. 121 122Responsibilities of these platform interfaces are - 123 124#. **Function : blx_plat_mboot_init()** 125 126 .. code-block:: c 127 128 void bl1_plat_mboot_init(void); 129 void bl2_plat_mboot_init(void); 130 131 Initialise all Measured Boot backends supported by the platform 132 (e.g. Event Log buffer, |RSE|). As these functions do not return any value, 133 the platform should deal with error management, such as logging the error 134 somewhere, or panicking the system if this is considered a fatal error. 135 136 - On the Arm FVP port - 137 138 - In BL1, this function is used to initialize the Event Log backend 139 driver, and also to write header information in the Event Log 140 buffer. 141 - In BL2, this function is used to initialize the Event Log buffer with 142 the information received from the BL1. It results in panic on 143 error. 144 145#. **Function : plat_mboot_measure_image()** 146 147 .. code-block:: c 148 149 int plat_mboot_measure_image(unsigned int image_id, 150 image_info_t *image_data); 151 152 - Measure the image using a hash function of the crypto module. 153 154 - Record the measurement in the corresponding backend - 155 156 - If it is Event Log backend, then record the measurement in TCG Event Log 157 format. 158 - If it is a secure crypto-processor (like |RSE|), then extend the 159 designated PCR (or store it in secure on-chip memory) with the given 160 measurement. 161 - This function must return 0 on success, a signed integer error code 162 otherwise. 163 - On the Arm FVP port, this function measures the given image and then 164 records that measurement in the Event Log buffer. 165 The passed id is used to retrieve information about on how to measure 166 the image (e.g. PCR number). 167 168#. **Function : blx_plat_mboot_finish()** 169 170 .. code-block:: c 171 172 void bl1_plat_mboot_finish(void); 173 void bl2_plat_mboot_finish(void); 174 175 - Do all teardown operations with respect to initialised Measured Boot backends. 176 This could be - 177 178 - Pass the Event Log details (start address and size) to Normal world or to 179 Secure World using any platform implementation way. 180 - Measure all critical data if any. 181 - As these functions do not return any value, the platform should deal with 182 error management, such as logging the error somewhere, or panicking the 183 system if this is considered a fatal error. 184 185 - On the Arm FVP port - 186 187 - In BL1, this function is used to pass the base address of 188 the Event Log buffer and its size to BL2 via tb_fw_config to extend the 189 Event Log buffer with the measurement of various images loaded by BL2. 190 It results in panic on error. 191 - In BL2, this function is used to pass the Event Log buffer information 192 (base address and size) to non-secure(BL33) and trusted OS(BL32) via 193 nt_fw and tos_fw config respectively. 194 See :ref:`DTB binding for Event Log properties` for a description of the 195 bindings used for Event Log properties. 196 197#. **Function : plat_mboot_measure_critical_data()** 198 199 .. code-block:: c 200 201 int plat_mboot_measure_critical_data(unsigned int critical_data_id, 202 const void *base, 203 size_t size); 204 205 This interface is not invoked by the generic code and it is up to the 206 platform layer to call it where appropriate. 207 208 This function measures the given critical data structure and records its 209 measurement using the Measured Boot backend driver. 210 This function must return 0 on success, a signed integer error code 211 otherwise. 212 213 In FVP, Non volatile counters get measured and recorded as Critical data 214 using the backend via this interface. 215 216#. **Function : plat_mboot_measure_key()** 217 218 .. code-block:: c 219 220 int plat_mboot_measure_key(const void *pk_oid, const void *pk_ptr, 221 size_t pk_len); 222 223 - This function is used by the platform to measure the passed key and 224 publicise it using any of the supported backends. 225 - The authentication module within the trusted boot framework calls this 226 function for every ROTPK involved in verifying the signature of a root 227 certificate and for every subsidiary key that gets extracted from a key 228 certificate for later authentication of a content certificate. 229 - A cookie, passed as the first argument, serves as a key-OID pointer 230 associated with the public key data, passed as the second argument. 231 - Public key data size is passed as the third argument to this function. 232 - This function must return 0 on success, a signed integer error code 233 otherwise. 234 - In Total Compute platform, this function is used to calculate the hash 235 of the given key and forward this hash to |RSE| alongside the measurement 236 of the image which the key signs. 237 238-------------- 239 240*Copyright (c) 2023-2025, Arm Limited. All rights reserved.* 241 242.. _Arm® Server Base Security Guide: https://developer.arm.com/documentation/den0086/latest 243.. _TCG EFI Protocol Specification: https://trustedcomputinggroup.org/wp-content/uploads/EFI-Protocol-Specification-rev13-160330final.pdf 244
