blob: 82be272bfe80b2efbb666ce959725ec592998c9a [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,
11Arm DEN0006D. It should be used in conjunction with the `Firmware Update`_
Douglas Raillardd7c21b72017-06-28 15:23:03 +010012design document, which implements a specific aspect of the TBBR.
13
14Chain of Trust
15--------------
16
17A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
Dan Handley610e7e12018-03-01 18:44:00 +000018the Arm development platforms, these components are:
Douglas Raillardd7c21b72017-06-28 15:23:03 +010019
20- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
21 trusted root-key storage registers.
22
23- The BL1 image, on the assumption that it resides in ROM so cannot be
24 tampered with.
25
26The remaining components in the CoT are either certificates or boot loader
27images. The certificates follow the `X.509 v3`_ standard. This standard
28enables adding custom extensions to the certificates, which are used to store
29essential information to establish the CoT.
30
31In the TBB CoT all certificates are self-signed. There is no need for a
32Certificate Authority (CA) because the CoT is not established by verifying the
33validity of a certificate's issuer but by the content of the certificate
34extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption
35signature scheme is used with a RSA key length of 2048 bits. Future version of
Dan Handley610e7e12018-03-01 18:44:00 +000036TF-A will support additional cryptographic algorithms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010037
38The certificates are categorised as "Key" and "Content" certificates. Key
39certificates are used to verify public keys which have been used to sign content
40certificates. Content certificates are used to store the hash of a boot loader
41image. An image can be authenticated by calculating its hash and matching it
42with the hash extracted from the content certificate. The SHA-256 function is
43used to calculate all hashes. The public keys and hashes are included as
44non-standard extension fields in the `X.509 v3`_ certificates.
45
46The keys used to establish the CoT are:
47
48- **Root of trust key**
49
50 The private part of this key is used to sign the BL2 content certificate and
51 the trusted key certificate. The public part is the ROTPK.
52
53- **Trusted world key**
54
55 The private part is used to sign the key certificates corresponding to the
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010056 secure world images (SCP_BL2, BL31 and BL32). The public part is stored in
Douglas Raillardd7c21b72017-06-28 15:23:03 +010057 one of the extension fields in the trusted world certificate.
58
59- **Non-trusted world key**
60
61 The private part is used to sign the key certificate corresponding to the
62 non secure world image (BL33). The public part is stored in one of the
63 extension fields in the trusted world certificate.
64
65- **BL3-X keys**
66
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010067 For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to
Douglas Raillardd7c21b72017-06-28 15:23:03 +010068 sign the content certificate for the BL3-X image. The public part is stored
69 in one of the extension fields in the corresponding key certificate.
70
71The following images are included in the CoT:
72
73- BL1
74- BL2
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010075- SCP_BL2 (optional)
Douglas Raillardd7c21b72017-06-28 15:23:03 +010076- BL31
77- BL33
78- BL32 (optional)
79
80The following certificates are used to authenticate the images.
81
82- **BL2 content certificate**
83
84 It is self-signed with the private part of the ROT key. It contains a hash
85 of the BL2 image.
86
87- **Trusted key certificate**
88
89 It is self-signed with the private part of the ROT key. It contains the
90 public part of the trusted world key and the public part of the non-trusted
91 world key.
92
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010093- **SCP_BL2 key certificate**
Douglas Raillardd7c21b72017-06-28 15:23:03 +010094
95 It is self-signed with the trusted world key. It contains the public part of
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010096 the SCP_BL2 key.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010097
Sandrine Bailleux15530dd2019-02-08 15:26:36 +010098- **SCP_BL2 content certificate**
Douglas Raillardd7c21b72017-06-28 15:23:03 +010099
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100100 It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100101 image.
102
103- **BL31 key certificate**
104
105 It is self-signed with the trusted world key. It contains the public part of
106 the BL31 key.
107
108- **BL31 content certificate**
109
110 It is self-signed with the BL31 key. It contains a hash of the BL31 image.
111
112- **BL32 key certificate**
113
114 It is self-signed with the trusted world key. It contains the public part of
115 the BL32 key.
116
117- **BL32 content certificate**
118
119 It is self-signed with the BL32 key. It contains a hash of the BL32 image.
120
121- **BL33 key certificate**
122
123 It is self-signed with the non-trusted world key. It contains the public
124 part of the BL33 key.
125
126- **BL33 content certificate**
127
128 It is self-signed with the BL33 key. It contains a hash of the BL33 image.
129
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100130The SCP_BL2 and BL32 certificates are optional, but they must be present if the
131corresponding SCP_BL2 or BL32 images are present.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100132
133Trusted Board Boot Sequence
134---------------------------
135
136The CoT is verified through the following sequence of steps. The system panics
137if any of the steps fail.
138
139- BL1 loads and verifies the BL2 content certificate. The issuer public key is
140 read from the verified certificate. A hash of that key is calculated and
141 compared with the hash of the ROTPK read from the trusted root-key storage
142 registers. If they match, the BL2 hash is read from the certificate.
143
Paul Beesleyba3ed402019-03-13 16:20:44 +0000144 .. note::
145 The matching operation is platform specific and is currently
146 unimplemented on the Arm development platforms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100147
148- BL1 loads the BL2 image. Its hash is calculated and compared with the hash
149 read from the certificate. Control is transferred to the BL2 image if all
150 the comparisons succeed.
151
152- BL2 loads and verifies the trusted key certificate. The issuer public key is
153 read from the verified certificate. A hash of that key is calculated and
154 compared with the hash of the ROTPK read from the trusted root-key storage
155 registers. If the comparison succeeds, BL2 reads and saves the trusted and
156 non-trusted world public keys from the verified certificate.
157
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100158The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images.
159The steps for the optional SCP_BL2 and BL32 images are skipped if these images
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100160are not present.
161
162- BL2 loads and verifies the BL3x key certificate. The certificate signature
163 is verified using the trusted world public key. If the signature
164 verification succeeds, BL2 reads and saves the BL3x public key from the
165 certificate.
166
167- BL2 loads and verifies the BL3x content certificate. The signature is
168 verified using the BL3x public key. If the signature verification succeeds,
169 BL2 reads and saves the BL3x image hash from the certificate.
170
171The next two steps are executed only for the BL33 image.
172
173- BL2 loads and verifies the BL33 key certificate. If the signature
174 verification succeeds, BL2 reads and saves the BL33 public key from the
175 certificate.
176
177- BL2 loads and verifies the BL33 content certificate. If the signature
178 verification succeeds, BL2 reads and saves the BL33 image hash from the
179 certificate.
180
181The next step is executed for all the boot loader images.
182
183- BL2 calculates the hash of each image. It compares it with the hash obtained
184 from the corresponding content certificate. The image authentication succeeds
185 if the hashes match.
186
187The Trusted Board Boot implementation spans both generic and platform-specific
188BL1 and BL2 code, and in tool code on the host build machine. The feature is
189enabled through use of specific build flags as described in the `User Guide`_.
190
191On the host machine, a tool generates the certificates, which are included in
192the FIP along with the boot loader images. These certificates are loaded in
193Trusted SRAM using the IO storage framework. They are then verified by an
Dan Handley610e7e12018-03-01 18:44:00 +0000194Authentication module included in TF-A.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100195
196The mechanism used for generating the FIP and the Authentication module are
197described in the following sections.
198
199Authentication Framework
200------------------------
201
Dan Handley610e7e12018-03-01 18:44:00 +0000202The authentication framework included in TF-A provides support to implement
203the desired trusted boot sequence. Arm platforms use this framework to
Sandrine Bailleux30918422019-04-24 10:41:24 +0200204implement the boot requirements specified in the `TBBR-client`_ document.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100205
206More information about the authentication framework can be found in the
207`Auth Framework`_ document.
208
209Certificate Generation Tool
210---------------------------
211
212The ``cert_create`` tool is built and runs on the host machine as part of the
Dan Handley610e7e12018-03-01 18:44:00 +0000213TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images
214and keys as inputs (keys must be in PEM format) and generates the
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100215certificates (in DER format) required to establish the CoT. New keys can be
216generated by the tool in case they are not provided. The certificates are then
217passed as inputs to the ``fiptool`` utility for creating the FIP.
218
219The certificates are also stored individually in the in the output build
220directory.
221
222The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL
223library version 1.0.1 or later to generate the X.509 certificates. Instructions
224for building and using the tool can be found in the `User Guide`_.
225
226--------------
227
Sandrine Bailleux30918422019-04-24 10:41:24 +0200228*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100229
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100230.. _Firmware Update: ../components/firmware-update.rst
Paul Beesley2437ddc2019-02-08 16:43:05 +0000231.. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt
Paul Beesleyea225122019-02-11 17:54:45 +0000232.. _User Guide: ../getting_started/user-guide.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100233.. _Auth Framework: auth-framework.rst
Sandrine Bailleux30918422019-04-24 10:41:24 +0200234.. _TBBR-client: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a
235.. _Trusted Board Boot Requirements (TBBR): `TBBR-client`_