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