1 Trusted Board Boot Design Guide 2 =============================== 3 4 Contents : 5 6 1. [Introduction](#1--introduction) 7 2. [Chain of Trust](#2--chain-of-trust) 8 3. [Trusted Board Boot Sequence](#3--trusted-board-boot-sequence) 9 4. [Authentication Module](#4--authentication-module) 10 5. [Certificate Generation Tool](#5--certificate-generation-tool) 11 12 13 1. Introduction 14 ---------------- 15 16 The Trusted Board Boot (TBB) feature prevents malicious firmware from running on 17 the platform by authenticating all firmware images up to and including the 18 normal world bootloader. It does this by establishing a Chain of Trust using 19 Public-Key-Cryptography Standards (PKCS). 20 21 This document describes the design of the ARM Trusted Firmware TBB 22 implementation. The current implementation is a proof of concept; future 23 versions will provide stronger architectural interfaces and implement the 24 missing functionality required in a production TBB-enabled system. 25 26 27 2. Chain of Trust 28 ------------------ 29 30 A Chain of Trust (CoT) starts with a set of implicitly trusted components. On 31 the ARM development platforms, these components are: 32 33 * A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the 34 trusted root-key storage registers. 35 36 * The BL1 image, on the assumption that it resides in ROM so cannot be 37 tampered with. 38 39 The remaining components in the CoT are either certificates or boot loader 40 images. The certificates follow the [X.509 v3] standard. This standard 41 enables adding custom extensions to the certificates, which are used to store 42 essential information to establish the CoT. 43 44 In the TBB CoT all certificates are self-signed. There is no need for a 45 Certificate Authority (CA) because the CoT is not established by verifying the 46 validity of a certificate's issuer but by the content of the certificate 47 extensions. To sign the certificates, the PKCS#1 SHA-1 with RSA Encryption 48 signature scheme is used with a RSA key length of 2048 bits. Future version of 49 Trusted Firmware will replace SHA-1 usage with SHA-256 and support additional 50 cryptographic algorithms. 51 52 The certificates are categorised as "Key" and "Content" certificates. Key 53 certificates are used to verify public keys which have been used to sign content 54 certificates. Content certificates are used to store the hash of a boot loader 55 image. An image can be authenticated by calculating its hash and matching it 56 with the hash extracted from the content certificate. The SHA-256 function is 57 used to calculate all hashes. The public keys and hashes are included as 58 non-standard extension fields in the [X.509 v3] certificates. 59 60 The keys used to establish the CoT are: 61 62 * **Root of trust key** 63 64 The private part of this key is used to sign the BL2 content certificate and 65 the trusted key certificate. The public part is the ROTPK. 66 67 * **Trusted world key** 68 69 The private part is used to sign the key certificates corresponding to the 70 secure world images (BL3-0, BL3-1 and BL3-2). The public part is stored in 71 one of the extension fields in the trusted world certificate. 72 73 * **Non-trusted world key** 74 75 The private part is used to sign the key certificate corresponding to the 76 non secure world image (BL3-3). The public part is stored in one of the 77 extension fields in the trusted world certificate. 78 79 * **BL3-X keys** 80 81 For each of BL3-0, BL3-1, BL3-2 and BL3-3, the private part is used to sign 82 the content certificate for the BL3-X image. The public part is stored in 83 one of the extension fields in the corresponding key certificate. 84 85 The following images are included in the CoT: 86 87 * BL1 88 * BL2 89 * BL3-0 (optional) 90 * BL3-1 91 * BL3-3 92 * BL3-2 (optional) 93 94 The following certificates are used to authenticate the images. 95 96 * **BL2 content certificate** 97 98 It is self-signed with the private part of the ROT key. It contains a hash 99 of the BL2 image. 100 101 * **Trusted key certificate** 102 103 It is self-signed with the private part of the ROT key. It contains the 104 public part of the trusted world key and the public part of the non-trusted 105 world key. 106 107 * **BL3-0 key certificate** 108 109 It is self-signed with the trusted world key. It contains the public part of 110 the BL3-0 key. 111 112 * **BL3-0 content certificate** 113 114 It is self-signed with the BL3-0 key. It contains a hash of the BL3-0 image. 115 116 * **BL3-1 key certificate** 117 118 It is self-signed with the trusted world key. It contains the public part of 119 the BL3-1 key. 120 121 * **BL3-1 content certificate** 122 123 It is self-signed with the BL3-1 key. It contains a hash of the BL3-1 image. 124 125 * **BL3-2 key certificate** 126 127 It is self-signed with the trusted world key. It contains the public part of 128 the BL3-2 key. 129 130 * **BL3-2 content certificate** 131 132 It is self-signed with the BL3-2 key. It contains a hash of the BL3-2 image. 133 134 * **BL3-3 key certificate** 135 136 It is self-signed with the non-trusted world key. It contains the public 137 part of the BL3-3 key. 138 139 * **BL3-3 content certificate** 140 141 It is self-signed with the BL3-3 key. It contains a hash of the BL3-3 image. 142 143 The BL3-0 and BL3-2 certificates are optional, but they must be present if the 144 corresponding BL3-0 or BL3-2 images are present. 145 146 147 3. Trusted Board Boot Sequence 148 ------------------------------- 149 150 The CoT is verified through the following sequence of steps. The system panics 151 if any of the steps fail. 152 153 * BL1 loads and verifies the BL2 content 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 they match, the BL2 hash is read from the certificate. 157 158 Note: the matching operation is platform specific and is currently 159 unimplemented on the ARM development platforms. 160 161 * BL1 loads the BL2 image. Its hash is calculated and compared with the hash 162 read from the certificate. Control is transferred to the BL2 image if all 163 the comparisons succeed. 164 165 * BL2 loads and verifies the trusted key certificate. The issuer public key is 166 read from the verified certificate. A hash of that key is calculated and 167 compared with the hash of the ROTPK read from the trusted root-key storage 168 registers. If the comparison succeeds, BL2 reads and saves the trusted and 169 non-trusted world public keys from the verified certificate. 170 171 The next two steps are executed for each of the BL3-0, BL3-1 & BL3-2 images. The 172 steps for the optional BL3-0 and BL3-2 images are skipped if these images are 173 not present. 174 175 * BL2 loads and verifies the BL3-x key certificate. The certificate signature 176 is verified using the trusted world public key. If the signature 177 verification succeeds, BL2 reads and saves the BL3-x public key from the 178 certificate. 179 180 * BL2 loads and verifies the BL3-x content certificate. The signature is 181 verified using the BL3-x public key. If the signature verification succeeds, 182 BL2 reads and saves the BL3-x image hash from the certificate. 183 184 The next two steps are executed only for the BL3-3 image. 185 186 * BL2 loads and verifies the BL3-3 key certificate. If the signature 187 verification succeeds, BL2 reads and saves the BL3-3 public key from the 188 certificate. 189 190 * BL2 loads and verifies the BL3-3 content certificate. If the signature 191 verification succeeds, BL2 reads and saves the BL3-3 image hash from the 192 certificate. 193 194 The next step is executed for all the boot loader images. 195 196 * BL2 calculates the hash of each image. It compares it with the hash obtained 197 from the corresponding content certificate. The image authentication succeeds 198 if the hashes match. 199 200 The Trusted Board Boot implementation spans both generic and platform-specific 201 BL1 and BL2 code, and in tool code on the host build machine. The feature is 202 enabled through use of specific build flags as described in the [User Guide]. 203 204 On the host machine, a tool generates the certificates, which are included in 205 the FIP along with the boot loader images. These certificates are loaded in 206 Trusted SRAM using the IO storage framework. They are then verified by an 207 Authentication module included in the Trusted Firmware. 208 209 The mechanism used for generating the FIP and the Authentication module are 210 described in the following sections. 211 212 213 4. Authentication Module 214 ------------------------- 215 216 The authentication module implements the required support to authenticate the 217 corresponding certificates or images at each step in the Trusted Board Boot 218 sequence. The module relies on the PolarSSL library (v1.3.9) to perform the 219 following operations: 220 221 * Parsing X.509 certificates and verifying them using SHA-1 with RSA 222 Encryption. 223 * Extracting public keys and hashes from the certificates. 224 * Generating hashes (SHA-256) of boot loader images 225 226 At each step, the module is responsible for allocating memory to store the 227 public keys or hashes that will be used in later steps. The step identifier is 228 used to determine what information must be saved, according to the CoT model 229 detailed in the previous sections. 230 231 The authentication module resides in the `common/auth/polarssl` directory. 232 Instructions for including the necessary modules of the PolarSSL SSL library and 233 building the authentication module can be found in the [User Guide]. 234 235 236 5. Certificate Generation Tool 237 ------------------------------- 238 239 The `cert_create` tool is built and runs on the host machine as part of the 240 Trusted Firmware build process when `GENERATE_COT=1`. It takes the boot loader 241 images and keys as inputs (keys must be in PEM format) and generates the 242 certificates (in DER format) required to establish the CoT. New keys can be 243 generated by the tool in case they are not provided. The certificates are then 244 passed as inputs to the `fip_create` tool for creating the FIP. 245 246 The certificates are also stored individually in the in the output build 247 directory. 248 249 The tool resides in the `tools/cert_create` directory. It uses OpenSSL SSL 250 library version 1.0.1 or later to generate the X.509 certificates. Instructions 251 for building and using the tool can be found in the [User Guide]. 252 253 254 - - - - - - - - - - - - - - - - - - - - - - - - - - 255 256 _Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._ 257 258 259 [X.509 v3]: http://www.ietf.org/rfc/rfc5280.txt 260 [X.690]: http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf 261 [User Guide]: user-guide.md 262
