1Trusted Board Boot Design Guide 2=============================== 3 4Contents : 5 61. [Introduction](#1--introduction) 72. [Chain of Trust](#2--chain-of-trust) 83. [Trusted Board Boot Sequence](#3--trusted-board-boot-sequence) 94. [Authentication Module](#4--authentication-module) 105. [Certificate Generation Tool](#5--certificate-generation-tool) 11 12 131. Introduction 14---------------- 15 16The Trusted Board Boot (TBB) feature prevents malicious firmware from running on 17the platform by authenticating all firmware images up to and including the 18normal world bootloader. It does this by establishing a Chain of Trust using 19Public-Key-Cryptography Standards (PKCS). 20 21This document describes the design of the ARM Trusted Firmware TBB 22implementation. The current implementation is a proof of concept; future 23versions will provide stronger architectural interfaces and implement the 24missing functionality required in a production TBB-enabled system. 25 26 272. Chain of Trust 28------------------ 29 30A Chain of Trust (CoT) starts with a set of implicitly trusted components. On 31the 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 39The remaining components in the CoT are either certificates or boot loader 40images. The certificates follow the [X.509 v3] standard. This standard 41enables adding custom extensions to the certificates, which are used to store 42essential information to establish the CoT. 43 44In the TBB CoT all certificates are self-signed. There is no need for a 45Certificate Authority (CA) because the CoT is not established by verifying the 46validity of a certificate's issuer but by the content of the certificate 47extensions. To sign the certificates, the PKCS#1 SHA-1 with RSA Encryption 48signature scheme is used with a RSA key length of 2048 bits. Future version of 49Trusted Firmware will replace SHA-1 usage with SHA-256 and support additional 50cryptographic algorithms. 51 52The certificates are categorised as "Key" and "Content" certificates. Key 53certificates are used to verify public keys which have been used to sign content 54certificates. Content certificates are used to store the hash of a boot loader 55image. An image can be authenticated by calculating its hash and matching it 56with the hash extracted from the content certificate. The SHA-256 function is 57used to calculate all hashes. The public keys and hashes are included as 58non-standard extension fields in the [X.509 v3] certificates. 59 60The 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 85The 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 94The 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 143The BL3-0 and BL3-2 certificates are optional, but they must be present if the 144corresponding BL3-0 or BL3-2 images are present. 145 146 1473. Trusted Board Boot Sequence 148------------------------------- 149 150The CoT is verified through the following sequence of steps. The system panics 151if 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 171The next two steps are executed for each of the BL3-0, BL3-1 & BL3-2 images. The 172steps for the optional BL3-0 and BL3-2 images are skipped if these images are 173not 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 184The 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 194The 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 200The Trusted Board Boot implementation spans both generic and platform-specific 201BL1 and BL2 code, and in tool code on the host build machine. The feature is 202enabled through use of specific build flags as described in the [User Guide]. 203 204On the host machine, a tool generates the certificates, which are included in 205the FIP along with the boot loader images. These certificates are loaded in 206Trusted SRAM using the IO storage framework. They are then verified by an 207Authentication module included in the Trusted Firmware. 208 209The mechanism used for generating the FIP and the Authentication module are 210described in the following sections. 211 212 2134. Authentication Module 214------------------------- 215 216The authentication module implements the required support to authenticate the 217corresponding certificates or images at each step in the Trusted Board Boot 218sequence. The module relies on the PolarSSL library (v1.3.9) to perform the 219following 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 226At each step, the module is responsible for allocating memory to store the 227public keys or hashes that will be used in later steps. The step identifier is 228used to determine what information must be saved, according to the CoT model 229detailed in the previous sections. 230 231The authentication module resides in the `common/auth/polarssl` directory. 232Instructions for including the necessary modules of the PolarSSL SSL library and 233building the authentication module can be found in the [User Guide]. 234 235 2365. Certificate Generation Tool 237------------------------------- 238 239The `cert_create` tool is built and runs on the host machine as part of the 240Trusted Firmware build process when `GENERATE_COT=1`. It takes the boot loader 241images and keys as inputs (keys must be in PEM format) and generates the 242certificates (in DER format) required to establish the CoT. New keys can be 243generated by the tool in case they are not provided. The certificates are then 244passed as inputs to the `fip_create` tool for creating the FIP. 245 246The certificates are also stored individually in the in the output build 247directory. 248 249The tool resides in the `tools/cert_create` directory. It uses OpenSSL SSL 250library version 1.0.1 or later to generate the X.509 certificates. Instructions 251for 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