blob: 51326f2eb3cccf57bf34ee8153d995cf609bd7e4 [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Trusted Board Boot
2==================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
Douglas Raillardd7c21b72017-06-28 15:23:03 +01004The Trusted Board Boot (TBB) feature prevents malicious firmware from running on
5the platform by authenticating all firmware images up to and including the
6normal world bootloader. It does this by establishing a Chain of Trust using
7Public-Key-Cryptography Standards (PKCS).
8
Sandrine Bailleux30918422019-04-24 10:41:24 +02009This document describes the design of Trusted Firmware-A (TF-A) TBB, which is an
10implementation of the `Trusted Board Boot Requirements (TBBR)`_ specification,
Paul Beesleyf8640672019-04-12 14:19:42 +010011Arm DEN0006D. It should be used in conjunction with the
12:ref:`Firmware Update (FWU)` design document, which implements a specific aspect
13of the TBBR.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010014
15Chain of Trust
16--------------
17
18A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
Dan Handley610e7e12018-03-01 18:44:00 +000019the Arm development platforms, these components are:
Douglas Raillardd7c21b72017-06-28 15:23:03 +010020
21- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +010022 trusted root-key storage registers. Alternatively, a development ROTPK might
23 be used and its hash embedded into the BL1 and BL2 images (only for
24 development purposes).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010025
26- The BL1 image, on the assumption that it resides in ROM so cannot be
27 tampered with.
28
29The remaining components in the CoT are either certificates or boot loader
30images. The certificates follow the `X.509 v3`_ standard. This standard
31enables adding custom extensions to the certificates, which are used to store
32essential information to establish the CoT.
33
34In the TBB CoT all certificates are self-signed. There is no need for a
35Certificate Authority (CA) because the CoT is not established by verifying the
36validity of a certificate's issuer but by the content of the certificate
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +010037extensions. To sign the certificates, different signature schemes are available,
38please refer to the :ref:`Build Options` for more details.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010039
40The certificates are categorised as "Key" and "Content" certificates. Key
41certificates are used to verify public keys which have been used to sign content
42certificates. Content certificates are used to store the hash of a boot loader
43image. An image can be authenticated by calculating its hash and matching it
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +010044with the hash extracted from the content certificate. Various hash algorithms
45are supported to calculate all hashes, please refer to the :ref:`Build Options`
46for more details.. The public keys and hashes are included as non-standard
47extension fields in the `X.509 v3`_ certificates.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010048
49The keys used to establish the CoT are:
50
51- **Root of trust key**
52
53 The private part of this key is used to sign the BL2 content certificate and
54 the trusted key certificate. The public part is the ROTPK.
55
56- **Trusted world key**
57
58 The private part is used to sign the key certificates corresponding to the
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010059 secure world images (SCP_BL2, BL31 and BL32). The public part is stored in
Douglas Raillardd7c21b72017-06-28 15:23:03 +010060 one of the extension fields in the trusted world certificate.
61
62- **Non-trusted world key**
63
64 The private part is used to sign the key certificate corresponding to the
65 non secure world image (BL33). The public part is stored in one of the
66 extension fields in the trusted world certificate.
67
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +010068- **BL3X keys**
Douglas Raillardd7c21b72017-06-28 15:23:03 +010069
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010070 For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +010071 sign the content certificate for the BL3X image. The public part is stored
Douglas Raillardd7c21b72017-06-28 15:23:03 +010072 in one of the extension fields in the corresponding key certificate.
73
74The following images are included in the CoT:
75
76- BL1
77- BL2
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010078- SCP_BL2 (optional)
Douglas Raillardd7c21b72017-06-28 15:23:03 +010079- BL31
80- BL33
81- BL32 (optional)
82
83The following certificates are used to authenticate the images.
84
85- **BL2 content certificate**
86
87 It is self-signed with the private part of the ROT key. It contains a hash
88 of the BL2 image.
89
90- **Trusted key certificate**
91
92 It is self-signed with the private part of the ROT key. It contains the
93 public part of the trusted world key and the public part of the non-trusted
94 world key.
95
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010096- **SCP_BL2 key certificate**
Douglas Raillardd7c21b72017-06-28 15:23:03 +010097
98 It is self-signed with the trusted world key. It contains the public part of
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010099 the SCP_BL2 key.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100100
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100101- **SCP_BL2 content certificate**
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100102
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100103 It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100104 image.
105
106- **BL31 key certificate**
107
108 It is self-signed with the trusted world key. It contains the public part of
109 the BL31 key.
110
111- **BL31 content certificate**
112
113 It is self-signed with the BL31 key. It contains a hash of the BL31 image.
114
115- **BL32 key certificate**
116
117 It is self-signed with the trusted world key. It contains the public part of
118 the BL32 key.
119
120- **BL32 content certificate**
121
122 It is self-signed with the BL32 key. It contains a hash of the BL32 image.
123
124- **BL33 key certificate**
125
126 It is self-signed with the non-trusted world key. It contains the public
127 part of the BL33 key.
128
129- **BL33 content certificate**
130
131 It is self-signed with the BL33 key. It contains a hash of the BL33 image.
132
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100133The SCP_BL2 and BL32 certificates are optional, but they must be present if the
134corresponding SCP_BL2 or BL32 images are present.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100135
136Trusted Board Boot Sequence
137---------------------------
138
139The CoT is verified through the following sequence of steps. The system panics
140if any of the steps fail.
141
142- BL1 loads and verifies the BL2 content certificate. The issuer public key is
143 read from the verified certificate. A hash of that key is calculated and
144 compared with the hash of the ROTPK read from the trusted root-key storage
145 registers. If they match, the BL2 hash is read from the certificate.
146
Paul Beesleyba3ed402019-03-13 16:20:44 +0000147 .. note::
148 The matching operation is platform specific and is currently
149 unimplemented on the Arm development platforms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100150
151- BL1 loads the BL2 image. Its hash is calculated and compared with the hash
152 read from the certificate. Control is transferred to the BL2 image if all
153 the comparisons succeed.
154
155- BL2 loads and verifies the trusted key certificate. The issuer public key is
156 read from the verified certificate. A hash of that key is calculated and
157 compared with the hash of the ROTPK read from the trusted root-key storage
158 registers. If the comparison succeeds, BL2 reads and saves the trusted and
159 non-trusted world public keys from the verified certificate.
160
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100161The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images.
162The steps for the optional SCP_BL2 and BL32 images are skipped if these images
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100163are not present.
164
165- BL2 loads and verifies the BL3x key certificate. The certificate signature
166 is verified using the trusted world public key. If the signature
167 verification succeeds, BL2 reads and saves the BL3x public key from the
168 certificate.
169
170- BL2 loads and verifies the BL3x content certificate. The signature is
171 verified using the BL3x public key. If the signature verification succeeds,
172 BL2 reads and saves the BL3x image hash from the certificate.
173
174The next two steps are executed only for the BL33 image.
175
176- BL2 loads and verifies the BL33 key certificate. If the signature
177 verification succeeds, BL2 reads and saves the BL33 public key from the
178 certificate.
179
180- BL2 loads and verifies the BL33 content certificate. If the signature
181 verification succeeds, BL2 reads and saves the BL33 image hash from the
182 certificate.
183
184The next step is executed for all the boot loader images.
185
186- BL2 calculates the hash of each image. It compares it with the hash obtained
187 from the corresponding content certificate. The image authentication succeeds
188 if the hashes match.
189
190The Trusted Board Boot implementation spans both generic and platform-specific
191BL1 and BL2 code, and in tool code on the host build machine. The feature is
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100192enabled through use of specific build flags as described in
193:ref:`Build Options`.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100194
195On the host machine, a tool generates the certificates, which are included in
196the FIP along with the boot loader images. These certificates are loaded in
197Trusted SRAM using the IO storage framework. They are then verified by an
Dan Handley610e7e12018-03-01 18:44:00 +0000198Authentication module included in TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100199
200The mechanism used for generating the FIP and the Authentication module are
201described in the following sections.
202
203Authentication Framework
204------------------------
205
Dan Handley610e7e12018-03-01 18:44:00 +0000206The authentication framework included in TF-A provides support to implement
207the desired trusted boot sequence. Arm platforms use this framework to
Paul Beesleyf8640672019-04-12 14:19:42 +0100208implement the boot requirements specified in the
209`Trusted Board Boot Requirements (TBBR)`_ document.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100210
211More information about the authentication framework can be found in the
Paul Beesleyf8640672019-04-12 14:19:42 +0100212:ref:`Authentication Framework & Chain of Trust` document.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100213
214Certificate Generation Tool
215---------------------------
216
217The ``cert_create`` tool is built and runs on the host machine as part of the
Dan Handley610e7e12018-03-01 18:44:00 +0000218TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images
Robin van der Gracht06b5cdb2023-09-12 11:16:23 +0200219and keys as inputs and generates the certificates (in DER format) required to
220establish the CoT. The input keys must either be a file in PEM format or a
221PKCS11 URI in case a HSM is used. New keys can be generated by the tool in
222case they are not provided. The certificates are then passed as inputs to
223the ``fiptool`` utility for creating the FIP.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100224
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +0100225The certificates are also stored individually in the output build directory.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100226
Paul Beesleyd2fcc4e2019-05-29 13:59:40 +0100227The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL
228library version to generate the X.509 certificates. The specific version of the
229library that is required is given in the :ref:`Prerequisites` document.
230
231Instructions for building and using the tool can be found at
232:ref:`tools_build_cert_create`.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100233
Sumit Gargc0c369c2019-11-15 18:47:53 +0530234Authenticated Encryption Framework
235----------------------------------
236
237The authenticated encryption framework included in TF-A provides support to
238implement the optional firmware encryption feature. This feature can be
239optionally enabled on platforms to implement the optional requirement:
240R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_
241document.
242
Sumit Gargc0c369c2019-11-15 18:47:53 +0530243Firmware Encryption Tool
244------------------------
245
246The ``encrypt_fw`` tool is built and runs on the host machine as part of the
247TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain
248firmware image as input and generates the encrypted firmware image which can
249then be passed as input to the ``fiptool`` utility for creating the FIP.
250
251The encrypted firmwares are also stored individually in the output build
252directory.
253
254The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL
255library version 1.0.1 or later to do authenticated encryption operation.
256Instructions for building and using the tool can be found in the
257:ref:`tools_build_enctool`.
258
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100259--------------
260
Sandrine Bailleux54b47dc2020-03-03 13:00:10 +0100261*Copyright (c) 2015-2020, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100262
Paul Beesley2437ddc2019-02-08 16:43:05 +0000263.. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
Sandrine Bailleuxf2384172024-02-02 11:16:12 +0100264.. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest