Douglas Raillard | 6f62574 | 2017-06-28 15:23:03 +0100 | [diff] [blame] | 1 | Trusted Board Boot Design Guide |
| 2 | =============================== |
| 3 | |
| 4 | |
| 5 | .. section-numbering:: |
| 6 | :suffix: . |
| 7 | |
| 8 | .. contents:: |
| 9 | |
| 10 | The Trusted Board Boot (TBB) feature prevents malicious firmware from running on |
| 11 | the platform by authenticating all firmware images up to and including the |
| 12 | normal world bootloader. It does this by establishing a Chain of Trust using |
| 13 | Public-Key-Cryptography Standards (PKCS). |
| 14 | |
| 15 | This document describes the design of ARM Trusted Firmware TBB, which is an |
| 16 | implementation of the Trusted Board Boot Requirements (TBBR) specification, |
| 17 | ARM DEN0006C-1. It should be used in conjunction with the `Firmware Update`_ |
| 18 | design document, which implements a specific aspect of the TBBR. |
| 19 | |
| 20 | Chain of Trust |
| 21 | -------------- |
| 22 | |
| 23 | A Chain of Trust (CoT) starts with a set of implicitly trusted components. On |
| 24 | the 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 | |
| 32 | The remaining components in the CoT are either certificates or boot loader |
| 33 | images. The certificates follow the `X.509 v3`_ standard. This standard |
| 34 | enables adding custom extensions to the certificates, which are used to store |
| 35 | essential information to establish the CoT. |
| 36 | |
| 37 | In the TBB CoT all certificates are self-signed. There is no need for a |
| 38 | Certificate Authority (CA) because the CoT is not established by verifying the |
| 39 | validity of a certificate's issuer but by the content of the certificate |
| 40 | extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption |
| 41 | signature scheme is used with a RSA key length of 2048 bits. Future version of |
| 42 | Trusted Firmware will support additional cryptographic algorithms. |
| 43 | |
| 44 | The certificates are categorised as "Key" and "Content" certificates. Key |
| 45 | certificates are used to verify public keys which have been used to sign content |
| 46 | certificates. Content certificates are used to store the hash of a boot loader |
| 47 | image. An image can be authenticated by calculating its hash and matching it |
| 48 | with the hash extracted from the content certificate. The SHA-256 function is |
| 49 | used to calculate all hashes. The public keys and hashes are included as |
| 50 | non-standard extension fields in the `X.509 v3`_ certificates. |
| 51 | |
| 52 | The 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 | |
| 77 | The following images are included in the CoT: |
| 78 | |
| 79 | - BL1 |
| 80 | - BL2 |
| 81 | - SCP\_BL2 (optional) |
| 82 | - BL31 |
| 83 | - BL33 |
| 84 | - BL32 (optional) |
| 85 | |
| 86 | The 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 | |
| 136 | The SCP\_BL2 and BL32 certificates are optional, but they must be present if the |
| 137 | corresponding SCP\_BL2 or BL32 images are present. |
| 138 | |
| 139 | Trusted Board Boot Sequence |
| 140 | --------------------------- |
| 141 | |
| 142 | The CoT is verified through the following sequence of steps. The system panics |
| 143 | if 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 | |
| 163 | The next two steps are executed for each of the SCP\_BL2, BL31 & BL32 images. |
| 164 | The steps for the optional SCP\_BL2 and BL32 images are skipped if these images |
| 165 | are 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 | |
| 176 | The 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 | |
| 186 | The 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 | |
| 192 | The Trusted Board Boot implementation spans both generic and platform-specific |
| 193 | BL1 and BL2 code, and in tool code on the host build machine. The feature is |
| 194 | enabled through use of specific build flags as described in the `User Guide`_. |
| 195 | |
| 196 | On the host machine, a tool generates the certificates, which are included in |
| 197 | the FIP along with the boot loader images. These certificates are loaded in |
| 198 | Trusted SRAM using the IO storage framework. They are then verified by an |
| 199 | Authentication module included in the Trusted Firmware. |
| 200 | |
| 201 | The mechanism used for generating the FIP and the Authentication module are |
| 202 | described in the following sections. |
| 203 | |
| 204 | Authentication Framework |
| 205 | ------------------------ |
| 206 | |
| 207 | The authentication framework included in the Trusted Firmware provides support |
| 208 | to implement the desired trusted boot sequence. ARM platforms use this framework |
| 209 | to implement the boot requirements specified in the TBBR-client document. |
| 210 | |
| 211 | More information about the authentication framework can be found in the |
| 212 | `Auth Framework`_ document. |
| 213 | |
| 214 | Certificate Generation Tool |
| 215 | --------------------------- |
| 216 | |
| 217 | The ``cert_create`` tool is built and runs on the host machine as part of the |
| 218 | Trusted Firmware build process when ``GENERATE_COT=1``. It takes the boot loader |
| 219 | images and keys as inputs (keys must be in PEM format) and generates the |
| 220 | certificates (in DER format) required to establish the CoT. New keys can be |
| 221 | generated by the tool in case they are not provided. The certificates are then |
| 222 | passed as inputs to the ``fiptool`` utility for creating the FIP. |
| 223 | |
| 224 | The certificates are also stored individually in the in the output build |
| 225 | directory. |
| 226 | |
| 227 | The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL |
| 228 | library version 1.0.1 or later to generate the X.509 certificates. Instructions |
| 229 | for 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 |