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