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