1Trusted Board Boot 2================== 3 4The Trusted Board Boot (TBB) feature prevents malicious firmware from running on 5the 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 12:ref:`Firmware Update (FWU)` design document, which implements a specific aspect 13of the TBBR. 14 15Chain of Trust 16-------------- 17 18A Chain of Trust (CoT) starts with a set of implicitly trusted components. On 19the Arm development platforms, these components are: 20 21- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the 22 trusted root-key storage registers. Alternatively, a development ROTPK might 23 be used and its hash embedded into the BL1 and BL2 images (only for 24 development purposes). 25 26- The BL1 image, on the assumption that it resides in ROM so cannot be 27 tampered with. 28 29The remaining components in the CoT are either certificates or boot loader 30images. The certificates follow the `X.509 v3`_ standard. This standard 31enables adding custom extensions to the certificates, which are used to store 32essential information to establish the CoT. 33 34In the TBB CoT all certificates are self-signed. There is no need for a 35Certificate Authority (CA) because the CoT is not established by verifying the 36validity of a certificate's issuer but by the content of the certificate 37extensions. To sign the certificates, different signature schemes are available, 38please refer to the :ref:`Build Options` for more details. 39 40The certificates are categorised as "Key" and "Content" certificates. Key 41certificates are used to verify public keys which have been used to sign content 42certificates. Content certificates are used to store the hash of a boot loader 43image. An image can be authenticated by calculating its hash and matching it 44with the hash extracted from the content certificate. Various hash algorithms 45are supported to calculate all hashes, please refer to the :ref:`Build Options` 46for more details.. The public keys and hashes are included as non-standard 47extension fields in the `X.509 v3`_ certificates. 48 49The keys used to establish the CoT are: 50 51- **Root of trust key** 52 53 The private part of this key is used to sign the BL2 content certificate and 54 the trusted key certificate. The public part is the ROTPK. 55 56- **Trusted world key** 57 58 The private part is used to sign the key certificates corresponding to the 59 secure world images (SCP_BL2, BL31 and BL32). The public part is stored in 60 one of the extension fields in the trusted world certificate. 61 62- **Non-trusted world key** 63 64 The private part is used to sign the key certificate corresponding to the 65 non secure world image (BL33). The public part is stored in one of the 66 extension fields in the trusted world certificate. 67 68- **BL3X keys** 69 70 For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to 71 sign the content certificate for the BL3X image. The public part is stored 72 in one of the extension fields in the corresponding key certificate. 73 74The following images are included in the CoT: 75 76- BL1 77- BL2 78- SCP_BL2 (optional) 79- BL31 80- BL33 81- BL32 (optional) 82 83The following certificates are used to authenticate the images. 84 85- **BL2 content certificate** 86 87 It is self-signed with the private part of the ROT key. It contains a hash 88 of the BL2 image. 89 90- **Trusted key certificate** 91 92 It is self-signed with the private part of the ROT key. It contains the 93 public part of the trusted world key and the public part of the non-trusted 94 world key. 95 96- **SCP_BL2 key certificate** 97 98 It is self-signed with the trusted world key. It contains the public part of 99 the SCP_BL2 key. 100 101- **SCP_BL2 content certificate** 102 103 It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2 104 image. 105 106- **BL31 key certificate** 107 108 It is self-signed with the trusted world key. It contains the public part of 109 the BL31 key. 110 111- **BL31 content certificate** 112 113 It is self-signed with the BL31 key. It contains a hash of the BL31 image. 114 115- **BL32 key certificate** 116 117 It is self-signed with the trusted world key. It contains the public part of 118 the BL32 key. 119 120- **BL32 content certificate** 121 122 It is self-signed with the BL32 key. It contains a hash of the BL32 image. 123 124- **BL33 key certificate** 125 126 It is self-signed with the non-trusted world key. It contains the public 127 part of the BL33 key. 128 129- **BL33 content certificate** 130 131 It is self-signed with the BL33 key. It contains a hash of the BL33 image. 132 133The SCP_BL2 and BL32 certificates are optional, but they must be present if the 134corresponding SCP_BL2 or BL32 images are present. 135 136Trusted Board Boot Sequence 137--------------------------- 138 139The CoT is verified through the following sequence of steps. The system panics 140if any of the steps fail. 141 142- BL1 loads and verifies the BL2 content certificate. The issuer public key is 143 read from the verified certificate. A hash of that key is calculated and 144 compared with the hash of the ROTPK read from the trusted root-key storage 145 registers. If they match, the BL2 hash is read from the certificate. 146 147 .. note:: 148 The matching operation is platform specific and is currently 149 unimplemented on the Arm development platforms. 150 151- BL1 loads the BL2 image. Its hash is calculated and compared with the hash 152 read from the certificate. Control is transferred to the BL2 image if all 153 the comparisons succeed. 154 155- BL2 loads and verifies the trusted key certificate. The issuer public key is 156 read from the verified certificate. A hash of that key is calculated and 157 compared with the hash of the ROTPK read from the trusted root-key storage 158 registers. If the comparison succeeds, BL2 reads and saves the trusted and 159 non-trusted world public keys from the verified certificate. 160 161The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images. 162The steps for the optional SCP_BL2 and BL32 images are skipped if these images 163are not present. 164 165- BL2 loads and verifies the BL3x key certificate. The certificate signature 166 is verified using the trusted world public key. If the signature 167 verification succeeds, BL2 reads and saves the BL3x public key from the 168 certificate. 169 170- BL2 loads and verifies the BL3x content certificate. The signature is 171 verified using the BL3x public key. If the signature verification succeeds, 172 BL2 reads and saves the BL3x image hash from the certificate. 173 174The next two steps are executed only for the BL33 image. 175 176- BL2 loads and verifies the BL33 key certificate. If the signature 177 verification succeeds, BL2 reads and saves the BL33 public key from the 178 certificate. 179 180- BL2 loads and verifies the BL33 content certificate. If the signature 181 verification succeeds, BL2 reads and saves the BL33 image hash from the 182 certificate. 183 184The next step is executed for all the boot loader images. 185 186- BL2 calculates the hash of each image. It compares it with the hash obtained 187 from the corresponding content certificate. The image authentication succeeds 188 if the hashes match. 189 190The Trusted Board Boot implementation spans both generic and platform-specific 191BL1 and BL2 code, and in tool code on the host build machine. The feature is 192enabled through use of specific build flags as described in 193:ref:`Build Options`. 194 195On the host machine, a tool generates the certificates, which are included in 196the FIP along with the boot loader images. These certificates are loaded in 197Trusted SRAM using the IO storage framework. They are then verified by an 198Authentication module included in TF-A. 199 200The mechanism used for generating the FIP and the Authentication module are 201described in the following sections. 202 203Authentication Framework 204------------------------ 205 206The authentication framework included in TF-A provides support to implement 207the desired trusted boot sequence. Arm platforms use this framework to 208implement the boot requirements specified in the 209`Trusted Board Boot Requirements (TBBR)`_ document. 210 211More information about the authentication framework can be found in the 212:ref:`Authentication Framework & Chain of Trust` document. 213 214Certificate Generation Tool 215--------------------------- 216 217The ``cert_create`` tool is built and runs on the host machine as part of the 218TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images 219and keys as inputs (keys must be in PEM format) and generates the 220certificates (in DER format) required to establish the CoT. New keys can be 221generated by the tool in case they are not provided. The certificates are then 222passed as inputs to the ``fiptool`` utility for creating the FIP. 223 224The certificates are also stored individually in the output build directory. 225 226The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL 227library version to generate the X.509 certificates. The specific version of the 228library that is required is given in the :ref:`Prerequisites` document. 229 230Instructions for building and using the tool can be found at 231:ref:`tools_build_cert_create`. 232 233Authenticated Encryption Framework 234---------------------------------- 235 236The authenticated encryption framework included in TF-A provides support to 237implement the optional firmware encryption feature. This feature can be 238optionally enabled on platforms to implement the optional requirement: 239R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_ 240document. 241 242Firmware Encryption Tool 243------------------------ 244 245The ``encrypt_fw`` tool is built and runs on the host machine as part of the 246TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain 247firmware image as input and generates the encrypted firmware image which can 248then be passed as input to the ``fiptool`` utility for creating the FIP. 249 250The encrypted firmwares are also stored individually in the output build 251directory. 252 253The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL 254library version 1.0.1 or later to do authenticated encryption operation. 255Instructions for building and using the tool can be found in the 256:ref:`tools_build_enctool`. 257 258-------------- 259 260*Copyright (c) 2015-2020, Arm Limited and Contributors. All rights reserved.* 261 262.. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt 263.. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a 264