1Trusted Board Boot 2================== 3 4The `Trusted Board Boot` (TBB) feature prevents malicious firmware from running 5on the platform by authenticating all firmware images up to and including the 6normal world bootloader. It does this by establishing a `Chain of Trust` using 7Public-Key-Cryptography Standards (PKCS). 8 9This document describes the design of Trusted Firmware-A (TF-A) TBB, which is an 10implementation of the `Trusted Board Boot Requirements (TBBR)`_ specification, 11Arm DEN0006D. It should be used in conjunction with the :ref:`Firmware Update 12(FWU)` design document, which implements a specific aspect of the TBBR. 13 14Chain of Trust 15-------------- 16 17A Chain of Trust (CoT) starts with a set of implicitly trusted components, which 18are used to establish trust in the next layer of components, and so on, in a 19`chained` manner. 20 21The chain of trust depends on several factors, including: 22 23- The set of firmware images in use on this platform. 24 Typically, most platforms share a common set of firmware images (BL1, BL2, 25 BL31, BL33) but extra platform-specific images might be required. 26 27- The key provisioning scheme: which keys need to programmed into the device 28 and at which stage during the platform's manufacturing lifecycle. 29 30- The key ownership model: who owns which key. 31 32As these vary across platforms, chains of trust also vary across 33platforms. Although each platform is free to define its own CoT based on its 34needs, TF-A provides a set of "default" CoTs fitting some typical trust models, 35which platforms may reuse. The rest of this section presents general concepts 36which apply to all these default CoTs. 37 38The implicitly trusted components forming the trust anchor are: 39 40- A Root of Trust Public Key (ROTPK), or a hash of it. 41 42 On Arm development platforms, a hash of the ROTPK (hash algorithm selected by 43 the ``HASH_ALG`` build option, with sha256 as default) is stored in the 44 trusted root-key storage registers. Alternatively, a development ROTPK might 45 be used and its hash embedded into the BL1 and BL2 images (only for 46 development purposes). 47 48- The BL1 image, on the assumption that it resides in ROM so cannot be 49 tampered with. 50 51The remaining components in the CoT are either certificates or boot loader 52images. The certificates follow the `X.509 v3`_ standard. This standard 53enables adding custom extensions to the certificates, which are used to store 54essential information to establish the CoT. 55 56All certificates are self-signed. There is no need for a Certificate Authority 57(CA) because the CoT is not established by verifying the validity of a 58certificate's issuer but by the content of the certificate extensions. To sign 59the certificates, different signature schemes are available, please refer to the 60:ref:`Build Options` for more details. 61 62The certificates are categorised as "Key" and "Content" certificates. Key 63certificates are used to verify public keys which have been used to sign content 64certificates. Content certificates are used to store the hash of a boot loader 65image. An image can be authenticated by calculating its hash and matching it 66with the hash extracted from the content certificate. Various hash algorithms 67are supported to calculate all hashes, please refer to the :ref:`Build Options` 68for more details. The public keys and hashes are included as non-standard 69extension fields in the `X.509 v3`_ certificates. 70 71The next sections now present specificities of each default CoT provided in 72TF-A. 73 74Default CoT #1: TBBR 75~~~~~~~~~~~~~~~~~~~~ 76 77The `TBBR` CoT is named after the specification it follows to the letter. 78 79In the TBBR CoT, all firmware binaries and certificates are (directly or 80indirectly) linked to the Root of Trust Public Key (ROTPK). Typically, the same 81vendor owns the ROTPK, the Trusted key and the Non-Trusted Key. Thus, this vendor 82is involved in signing every BL3x Key Certificate. 83 84The keys used to establish this CoT are: 85 86- **Root of trust key** 87 88 The private part of this key is used to sign the trusted boot firmware 89 certificate and the trusted key certificate. The public part is the ROTPK. 90 91- **Trusted world key** 92 93 The private part is used to sign the key certificates corresponding to the 94 secure world images (SCP_BL2, BL31 and BL32). The public part is stored in 95 one of the extension fields in the trusted key certificate. 96 97- **Non-trusted world key** 98 99 The private part is used to sign the key certificate corresponding to the 100 non-secure world image (BL33). The public part is stored in one of the 101 extension fields in the trusted key certificate. 102 103- **BL3X keys** 104 105 For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to 106 sign the content certificate for the BL3X image. The public part is stored 107 in one of the extension fields in the corresponding key certificate. 108 109The following images are included in the CoT: 110 111- BL1 112- BL2 113- SCP_BL2 (optional) 114- BL31 115- BL33 116- BL32 (optional) 117 118The following certificates are used to authenticate the images. 119 120- **Trusted boot firmware certificate** 121 122 It is self-signed with the private part of the ROT key. It contains a hash of 123 the BL2 image and hashes of various firmware configuration files 124 (TB_FW_CONFIG, HW_CONFIG, FW_CONFIG). 125 126- **Trusted key certificate** 127 128 It is self-signed with the private part of the ROT key. It contains the 129 public part of the trusted world key and the public part of the non-trusted 130 world key. 131 132- **SCP firmware key certificate** 133 134 It is self-signed with the trusted world key. It contains the public part of 135 the SCP_BL2 key. 136 137- **SCP firmware content certificate** 138 139 It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2 140 image. 141 142- **SoC firmware key certificate** 143 144 It is self-signed with the trusted world key. It contains the public part of 145 the BL31 key. 146 147- **SoC firmware content certificate** 148 149 It is self-signed with the BL31 key. It contains hashes of the BL31 image and 150 its configuration file (SOC_FW_CONFIG). 151 152- **Trusted OS key certificate** 153 154 It is self-signed with the trusted world key. It contains the public part of 155 the BL32 key. 156 157- **Trusted OS content certificate** 158 159 It is self-signed with the BL32 key. It contains hashes of the BL32 image(s) 160 and its configuration file(s) (TOS_FW_CONFIG). 161 162- **Non-trusted firmware key certificate** 163 164 It is self-signed with the non-trusted world key. It contains the public 165 part of the BL33 key. 166 167- **Non-trusted firmware content certificate** 168 169 It is self-signed with the BL33 key. It contains hashes of the BL33 image and 170 its configuration file (NT_FW_CONFIG). 171 172The SCP firmware and Trusted OS certificates are optional, but they must be 173present if the corresponding SCP_BL2 or BL32 images are present. 174 175The following diagram summarizes the part of the TBBR CoT enforced by BL2. Some 176images (SCP, debug certificates, secure partitions, configuration files) are not 177shown here for conciseness: 178 179.. image:: ../resources/diagrams/cot-tbbr.jpg 180 181Default CoT #2: Dualroot 182~~~~~~~~~~~~~~~~~~~~~~~~ 183 184The `dualroot` CoT is targeted at systems where the Normal World firmware is 185owned by a different entity than the Secure World Firmware, and those 2 entities 186do not wish to share any keys or have any dependency between each other when it 187comes to signing their respective images. It establishes 2 separate signing 188domains, each with its own Root of Trust key. In that sense, this CoT has 2 189roots of trust, hence the `dualroot` name. 190 191Although the dualroot CoT reuses some of the TBBR CoT components and concepts, 192it differs on the BL33 image's chain of trust, which is rooted into a new key, 193called `Platform ROTPK`, or `PROTPK` for short. 194 195The following diagram summarizes the part of the dualroot CoT enforced by 196BL2. Some images (SCP, debug certificates, secure partitions, configuration 197files) are not shown here for conciseness: 198 199.. image:: ../resources/diagrams/cot-dualroot.jpg 200 201Default CoT #3: CCA 202~~~~~~~~~~~~~~~~~~~ 203 204This CoT is targeted at Arm CCA systems. The Arm CCA security model recommends 205making supply chains for the Arm CCA firmware, the secure world firmware and the 206platform owner firmware, independent. Hence, this CoT has 3 roots of trust, one 207for each supply chain. 208 209Trusted Board Boot Sequence 210--------------------------- 211 212The CoT is verified through the following sequence of steps. The system panics 213if any of the steps fail. 214 215- BL1 loads and verifies the BL2 content certificate. The issuer public key is 216 read from the verified certificate. A hash of that key is calculated and 217 compared with the hash of the ROTPK read from the trusted root-key storage 218 registers. If they match, the BL2 hash is read from the certificate. 219 220 .. note:: 221 The matching operation is platform specific and is currently 222 unimplemented on the Arm development platforms. 223 224- BL1 loads the BL2 image. Its hash is calculated and compared with the hash 225 read from the certificate. Control is transferred to the BL2 image if all 226 the comparisons succeed. 227 228- BL2 loads and verifies the trusted key certificate. The issuer public key is 229 read from the verified certificate. A hash of that key is calculated and 230 compared with the hash of the ROTPK read from the trusted root-key storage 231 registers. If the comparison succeeds, BL2 reads and saves the trusted and 232 non-trusted world public keys from the verified certificate. 233 234The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images. 235The steps for the optional SCP_BL2 and BL32 images are skipped if these images 236are not present. 237 238- BL2 loads and verifies the BL3x key certificate. The certificate signature 239 is verified using the trusted world public key. If the signature 240 verification succeeds, BL2 reads and saves the BL3x public key from the 241 certificate. 242 243- BL2 loads and verifies the BL3x content certificate. The signature is 244 verified using the BL3x public key. If the signature verification succeeds, 245 BL2 reads and saves the BL3x image hash from the certificate. 246 247The next two steps are executed only for the BL33 image. 248 249- BL2 loads and verifies the BL33 key certificate. If the signature 250 verification succeeds, BL2 reads and saves the BL33 public key from the 251 certificate. 252 253- BL2 loads and verifies the BL33 content certificate. If the signature 254 verification succeeds, BL2 reads and saves the BL33 image hash from the 255 certificate. 256 257The next step is executed for all the boot loader images. 258 259- BL2 calculates the hash of each image. It compares it with the hash obtained 260 from the corresponding content certificate. The image authentication succeeds 261 if the hashes match. 262 263The Trusted Board Boot implementation spans both generic and platform-specific 264BL1 and BL2 code, and in tool code on the host build machine. The feature is 265enabled through use of specific build flags as described in 266:ref:`Build Options`. 267 268On the host machine, a tool generates the certificates, which are included in 269the FIP along with the boot loader images. These certificates are loaded in 270Trusted SRAM using the IO storage framework. They are then verified by an 271Authentication module included in TF-A. 272 273The mechanism used for generating the FIP and the Authentication module are 274described in the following sections. 275 276Authentication Framework 277------------------------ 278 279The authentication framework included in TF-A provides support to implement 280the desired trusted boot sequence. Arm platforms use this framework to 281implement the boot requirements specified in the 282`Trusted Board Boot Requirements (TBBR)`_ document. 283 284More information about the authentication framework can be found in the 285:ref:`Authentication Framework & Chain of Trust` document. 286 287Certificate Generation Tool 288--------------------------- 289 290The ``cert_create`` tool is built and runs on the host machine as part of the 291TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images 292and keys as inputs and generates the certificates (in DER format) required to 293establish the CoT. The input keys must either be a file in PEM format or a 294PKCS11 URI in case a HSM is used. New keys can be generated by the tool in 295case they are not provided. The certificates are then passed as inputs to 296the ``fiptool`` utility for creating the FIP. 297 298The certificates are also stored individually in the output build directory. 299 300The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL 301library version to generate the X.509 certificates. The specific version of the 302library that is required is given in the :ref:`Prerequisites` document. 303 304Instructions for building and using the tool can be found at 305:ref:`tools_build_cert_create`. 306 307Authenticated Encryption Framework 308---------------------------------- 309 310The authenticated encryption framework included in TF-A provides support to 311implement the optional firmware encryption feature. This feature can be 312optionally enabled on platforms to implement the optional requirement: 313R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_ 314document. 315 316Firmware Encryption Tool 317------------------------ 318 319The ``encrypt_fw`` tool is built and runs on the host machine as part of the 320TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain 321firmware image as input and generates the encrypted firmware image which can 322then be passed as input to the ``fiptool`` utility for creating the FIP. 323 324The encrypted firmwares are also stored individually in the output build 325directory. 326 327The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL 328library version 1.0.1 or later to do authenticated encryption operation. 329Instructions for building and using the tool can be found in the 330:ref:`tools_build_enctool`. 331 332-------------- 333 334*Copyright (c) 2015-2024, Arm Limited and Contributors. All rights reserved.* 335 336.. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt 337.. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest 338
