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