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