blob: 9dfe494153bff0954f2f206aa3f12062a7c52ece [file] [log] [blame]
Manish V Badarkheb2def912023-06-12 21:33:35 +01001Measured 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 recordsthe 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
Tamas Bana7bf68d2024-02-21 13:55:31 +010094#. RSE
Manish V Badarkheb2def912023-06-12 21:33:35 +010095
96 It is one of physical backend to extend the measurements. Please refer this
Tamas Bana7bf68d2024-02-21 13:55:31 +010097 document :ref:`Runtime Security Engine (RSE)` for more details.
Manish V Badarkheb2def912023-06-12 21:33:35 +010098
99Platform Interface
100------------------
101
102Every image which gets successfully loaded in memory (and authenticated, if
103trusted boot is enabled) then gets measured. In addition to that, platforms
104can measure any relevant piece of critical data at any point during the boot.
105The following diagram outlines the call sequence for Measured Boot platform
106interfaces invoked from generic code:
107
108.. image:: ../resources/diagrams/measured_boot_design.png
109
110These platform interfaces are used by BL1 and BL2 only, and are declared in
111``include/plat/common/platform.h``.
112BL31 does not load and thus does not measure any image.
113
114Responsibilities of these platform interfaces are -
115
116#. **Function : blx_plat_mboot_init()**
117
118 .. code-block:: c
119
120 void bl1_plat_mboot_init(void);
121 void bl2_plat_mboot_init(void);
122
123 Initialise all Measured Boot backends supported by the platform
Tamas Bana7bf68d2024-02-21 13:55:31 +0100124 (e.g. Event Log buffer, RSE). As these functions do not return any value,
Manish V Badarkheb2def912023-06-12 21:33:35 +0100125 the platform should deal with error management, such as logging the error
126 somewhere, or panicking the system if this is considered a fatal error.
127
128 - On the Arm FVP port -
129
130 - In BL1, this function is used to initialize the Event Log backend
131 driver, and also to write header information in the Event Log
132 buffer.
133 - In BL2, this function is used to initialize the Event Log buffer with
134 the information received from the BL1. It results in panic on
135 error.
136
137#. **Function : plat_mboot_measure_image()**
138
139 .. code-block:: c
140
141 int plat_mboot_measure_image(unsigned int image_id,
142 image_info_t *image_data);
143
144 - Measure the image using a hash function of the crypto module.
145
146 - Record the measurement in the corresponding backend -
147
148 - If it is Event Log backend, then record the measurement in TCG Event Log
149 format.
Tamas Bana7bf68d2024-02-21 13:55:31 +0100150 - If it is a secure crypto-processor (like RSE), then extend the designated
Manish V Badarkheb2def912023-06-12 21:33:35 +0100151 PCR (or slot) with the given measurement.
152 - This function must return 0 on success, a signed integer error code
153 otherwise.
154 - On the Arm FVP port, this function measures the given image and then
155 records that measurement in the Event Log buffer.
156 The passed id is used to retrieve information about on how to measure
157 the image (e.g. PCR number).
158
159#. **Function : blx_plat_mboot_finish()**
160
161 .. code-block:: c
162
163 void bl1_plat_mboot_finish(void);
164 void bl2_plat_mboot_finish(void);
165
166 - Do all teardown operations with respect to initialised Measured Boot backends.
167 This could be -
168
169 - Pass the Event Log details (start address and size) to Normal world or to
170 Secure World using any platform implementation way.
171 - Measure all critical data if any.
172 - As these functions do not return any value, the platform should deal with
173 error management, such as logging the error somewhere, or panicking the
174 system if this is considered a fatal error.
175
176 - On the Arm FVP port -
177
178 - In BL1, this function is used to pass the base address of
179 the Event Log buffer and its size to BL2 via tb_fw_config to extend the
180 Event Log buffer with the measurement of various images loaded by BL2.
181 It results in panic on error.
182 - In BL2, this function is used to pass the Event Log buffer information
183 (base address and size) to non-secure(BL33) and trusted OS(BL32) via
184 nt_fw and tos_fw config respectively.
185 See :ref:`DTB binding for Event Log properties` for a description of the
186 bindings used for Event Log properties.
187
188#. **Function : plat_mboot_measure_critical_data()**
189
190 .. code-block:: c
191
192 int plat_mboot_measure_critical_data(unsigned int critical_data_id,
193 const void *base,
194 size_t size);
195
196 This interface is not invoked by the generic code and it is up to the
197 platform layer to call it where appropriate.
198
199 This function measures the given critical data structure and records its
200 measurement using the Measured Boot backend driver.
201 This function must return 0 on success, a signed integer error code
202 otherwise.
203
204 In FVP, Non volatile counters get measured and recorded as Critical data
205 using the backend via this interface.
206
Manish V Badarkhedfe5e7d2023-04-11 21:34:52 +0100207#. **Function : plat_mboot_measure_key()**
208
209 .. code-block:: c
210
211 int plat_mboot_measure_key(const void *pk_oid, const void *pk_ptr,
212 size_t pk_len);
213
214 - This function is used by the platform to measure the passed key and
215 publicise it using any of the supported backends.
216 - The authentication module within the trusted boot framework calls this
217 function for every ROTPK involved in verifying the signature of a root
218 certificate and for every subsidiary key that gets extracted from a key
219 certificate for later authentication of a content certificate.
220 - A cookie, passed as the first argument, serves as a key-OID pointer
221 associated with the public key data, passed as the second argument.
222 - Public key data size is passed as the third argument to this function.
223 - This function must return 0 on success, a signed integer error code
224 otherwise.
Manish V Badarkhe3136d962023-11-07 17:49:36 +0000225 - In TC2 platform, this function is used to calculate the hash of the given
Tamas Bana7bf68d2024-02-21 13:55:31 +0100226 key and forward this hash to RSE alongside the measurement of the image
Manish V Badarkhedfe5e7d2023-04-11 21:34:52 +0100227 which the key signs.
228
Manish V Badarkheb2def912023-06-12 21:33:35 +0100229--------------
230
231*Copyright (c) 2023, Arm Limited. All rights reserved.*
232
233.. _Arm® Server Base Security Guide: https://developer.arm.com/documentation/den0086/latest
234.. _TCG EFI Protocol Specification: https://trustedcomputinggroup.org/wp-content/uploads/EFI-Protocol-Specification-rev13-160330final.pdf