docs/design/trusted-board-boot.rst

5 on the platform by authenticating all firmware images up to and including the
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 :ref:`Firmware Update
12 (FWU)` design document, which implements a specific aspect of the TBBR.
18 are used to establish trust in the next layer of components, and so on, in a
27 -  The key provisioning scheme: which keys need to programmed into the device
28    and at which stage during the platform's manufacturing lifecycle.
38 The implicitly trusted components forming the trust anchor are:
42    On Arm development platforms, a hash of the ROTPK (hash algorithm selected by
43    the ``HASH_ALG`` build option, with sha256 as default) is stored in the
45    be used and its hash embedded into the BL1 and BL2 images (only for
48 -  The BL1 image, on the assumption that it resides in ROM so cannot be
51 The remaining components in the CoT are either certificates or boot loader
52 images. The certificates follow the `X.509 v3`_ standard. This standard
53 enables adding custom extensions to the certificates, which are used to store
54 essential information to establish the CoT.
57 (CA) because the CoT is not established by verifying the validity of a
58 certificate's issuer but by the content of the certificate extensions. To sign
59 the certificates, different signature schemes are available, please refer to the
64 certificates. Content certificates are used to store the hash of a boot loader
66 with the hash extracted from the content certificate. Various hash algorithms
67 are supported to calculate all hashes, please refer to the :ref:`Build Options`
69 extension fields in the `X.509 v3`_ certificates.
77 The `TBBR` CoT is named after the specification it follows to the letter.
79 In the TBBR CoT, all firmware binaries and certificates are (directly or
80 indirectly) linked to the Root of Trust Public Key (ROTPK). Typically, the same
81 vendor owns the ROTPK, the Trusted key and the Non-Trusted Key. Thus, this vendor
88    The private part of this key is used to sign the trusted boot firmware
89    certificate and the trusted key certificate. The public part is the ROTPK.
93    The private part is used to sign the key certificates corresponding to the
95    one of the extension fields in the trusted key certificate.
99    The private part is used to sign the key certificate corresponding to the
100    non-secure world image (BL33). The public part is stored in one of the
101    extension fields in the trusted key certificate.
105    For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to
106    sign the content certificate for the BL3X image. The public part is stored
107    in one of the extension fields in the corresponding key certificate.
109 The following images are included in the CoT:
118 The following certificates are used to authenticate the images.
122    It is self-signed with the private part of the ROT key. It contains a hash of
123    the BL2 image and hashes of various firmware configuration files
128    It is self-signed with the private part of the ROT key. It contains the
129    public part of the trusted world key and the public part of the non-trusted
134    It is self-signed with the trusted world key. It contains the public part of
135    the SCP_BL2 key.
139    It is self-signed with the SCP_BL2 key. It contains a hash of the SCP_BL2
144    It is self-signed with the trusted world key. It contains the public part of
145    the BL31 key.
149    It is self-signed with the BL31 key. It contains hashes of the BL31 image and
154    It is self-signed with the trusted world key. It contains the public part of
155    the BL32 key.
159    It is self-signed with the BL32 key. It contains hashes of the BL32 image(s)
164    It is self-signed with the non-trusted world key. It contains the public
165    part of the BL33 key.
169    It is self-signed with the BL33 key. It contains hashes of the BL33 image and
173 present if the corresponding SCP_BL2 or BL32 images are present.
175 The following diagram summarizes the part of the TBBR CoT enforced by BL2. Some
184 The `dualroot` CoT is targeted at systems where the Normal World firmware is
185 owned by a different entity than the Secure World Firmware, and those 2 entities
189 roots of trust, hence the `dualroot` name.
191 Although the dualroot CoT reuses some of the TBBR CoT components and concepts,
192 it differs on the BL33 image's chain of trust, which is rooted into a new key,
195 The following diagram summarizes the part of the dualroot CoT enforced by
205 making supply chains for the Arm CCA firmware, the secure world firmware and the
212 The CoT is verified through the following sequence of steps. The system panics
213 if any of the steps fail.
215 -  BL1 loads and verifies the BL2 content certificate. The issuer public key is
216    read from the verified certificate. A hash of that key is calculated and
217    compared with the hash of the ROTPK read from the trusted root-key storage
218    registers. If they match, the BL2 hash is read from the certificate.
222       unimplemented on the Arm development platforms.
224 -  BL1 loads the BL2 image. Its hash is calculated and compared with the hash
225    read from the certificate. Control is transferred to the BL2 image if all
226    the comparisons succeed.
228 -  BL2 loads and verifies the trusted key certificate. The issuer public key is
229    read from the verified certificate. A hash of that key is calculated and
230    compared with the hash of the ROTPK read from the trusted root-key storage
231    registers. If the comparison succeeds, BL2 reads and saves the trusted and
232    non-trusted world public keys from the verified certificate.
234 The next two steps are executed for each of the SCP_BL2, BL31 & BL32 images.
235 The steps for the optional SCP_BL2 and BL32 images are skipped if these images
238 -  BL2 loads and verifies the BL3x key certificate. The certificate signature
239    is verified using the trusted world public key. If the signature
240    verification succeeds, BL2 reads and saves the BL3x public key from the
243 -  BL2 loads and verifies the BL3x content certificate. The signature is
244    verified using the BL3x public key. If the signature verification succeeds,
245    BL2 reads and saves the BL3x image hash from the certificate.
247 The next two steps are executed only for the BL33 image.
249 -  BL2 loads and verifies the BL33 key certificate. If the signature
250    verification succeeds, BL2 reads and saves the BL33 public key from the
253 -  BL2 loads and verifies the BL33 content certificate. If the signature
254    verification succeeds, BL2 reads and saves the BL33 image hash from the
257 The next step is executed for all the boot loader images.
259 -  BL2 calculates the hash of each image. It compares it with the hash obtained
260    from the corresponding content certificate. The image authentication succeeds
261    if the hashes match.
264 BL1 and BL2 code, and in tool code on the host build machine. The feature is
268 On the host machine, a tool generates the certificates, which are included in
269 the FIP along with the boot loader images. These certificates are loaded in
270 Trusted SRAM using the IO storage framework. They are then verified by an
273 The mechanism used for generating the FIP and the Authentication module are
274 described in the following sections.
280 the desired trusted boot sequence. Arm platforms use this framework to
281 implement the boot requirements specified in the
284 More information about the authentication framework can be found in the
290 The ``cert_create`` tool is built and runs on the host machine as part of the
291 TF-A build process when ``GENERATE_COT=1``. It takes the boot loader images
292 and keys as inputs and generates the certificates (in DER format) required to
293 establish the CoT. The input keys must either be a file in PEM format or a
294 PKCS11 URI in case a HSM is used. New keys can be generated by the tool in
296 the ``fiptool`` utility for creating the FIP.
298 The certificates are also stored individually in the output build directory.
300 The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL
301 library version to generate the X.509 certificates. The specific version of the
302 library that is required is given in the :ref:`Prerequisites` document.
304 Instructions for building and using the tool can be found at
311 implement the optional firmware encryption feature. This feature can be
312 optionally enabled on platforms to implement the optional requirement:
313 R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_
319 The ``encrypt_fw`` tool is built and runs on the host machine as part of the
320 TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain
321 firmware image as input and generates the encrypted firmware image which can
322 then be passed as input to the ``fiptool`` utility for creating the FIP.
324 The encrypted firmwares are also stored individually in the output build
327 The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL
329 Instructions for building and using the tool can be found in the