CTCaer/switch-l4t-atf
1
0
Fork 0
mirror of https://github.com/CTCaer/switch-l4t-atf.git synced 2024-12-13 21:58:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
279fedc1f8
switch-l4t-atf/docs/trusted-board-boot.rst
Douglas Raillard 6f62574767 Convert documentation to reStructuredText 
Due to recent issues in the rendering of the documentation on GitHub and
some long-standing issues like the lack of automatic table of content in
Markdown, the documentation has been converted to reStructuredText.
Basic constructs looks pretty similar to Markdown.

Automatically convert GitHub markdown documentation to reStructuredText
using pandoc.

Change-Id: If20b695acedc6d1b49c8d9fb64efd6b6ba23f4a9
Signed-off-by: Douglas Raillard <douglas.raillard@arm.com>
2017-06-29 11:47:09 +01:00

239 lines
9.2 KiB
ReStructuredText
Raw Blame History

Trusted Board Boot Design Guide
===============================
.. section-numbering::
:suffix: .
.. contents::
The Trusted Board Boot (TBB) feature prevents malicious firmware from running on
the platform by authenticating all firmware images up to and including the
normal world bootloader. It does this by establishing a Chain of Trust using
Public-Key-Cryptography Standards (PKCS).
This document describes the design of ARM Trusted Firmware TBB, which is an
implementation of the Trusted Board Boot Requirements (TBBR) specification,
ARM DEN0006C-1. It should be used in conjunction with the `Firmware Update`_
design document, which implements a specific aspect of the TBBR.
Chain of Trust
--------------
A Chain of Trust (CoT) starts with a set of implicitly trusted components. On
the ARM development platforms, these components are:
- A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the
trusted root-key storage registers.
- The BL1 image, on the assumption that it resides in ROM so cannot be
tampered with.
The remaining components in the CoT are either certificates or boot loader
images. The certificates follow the `X.509 v3`_ standard. This standard
enables adding custom extensions to the certificates, which are used to store
essential information to establish the CoT.
In the TBB CoT all certificates are self-signed. There is no need for a
Certificate Authority (CA) because the CoT is not established by verifying the
validity of a certificate's issuer but by the content of the certificate
extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption
signature scheme is used with a RSA key length of 2048 bits. Future version of
Trusted Firmware will support additional cryptographic algorithms.
The certificates are categorised as "Key" and "Content" certificates. Key
certificates are used to verify public keys which have been used to sign content
certificates. Content certificates are used to store the hash of a boot loader
image. An image can be authenticated by calculating its hash and matching it
with the hash extracted from the content certificate. The SHA-256 function is
used to calculate all hashes. The public keys and hashes are included as
non-standard extension fields in the `X.509 v3`_ certificates.
The keys used to establish the CoT are:
- **Root of trust key**
The private part of this key is used to sign the BL2 content certificate and
the trusted key certificate. The public part is the ROTPK.
- **Trusted world key**
The private part is used to sign the key certificates corresponding to the
secure world images (SCP\_BL2, BL31 and BL32). The public part is stored in
one of the extension fields in the trusted world certificate.
- **Non-trusted world key**
The private part is used to sign the key certificate corresponding to the
non secure world image (BL33). The public part is stored in one of the
extension fields in the trusted world certificate.
- **BL3-X keys**
For each of SCP\_BL2, BL31, BL32 and BL33, the private part is used to
sign the content certificate for the BL3-X image. The public part is stored
in one of the extension fields in the corresponding key certificate.
The following images are included in the CoT:
- BL1
- BL2
- SCP\_BL2 (optional)
- BL31
- BL33
- BL32 (optional)
The following certificates are used to authenticate the images.
- **BL2 content certificate**
It is self-signed with the private part of the ROT key. It contains a hash
of the BL2 image.
- **Trusted key certificate**
It is self-signed with the private part of the ROT key. It contains the
public part of the trusted world key and the public part of the non-trusted
world key.
- **SCP\_BL2 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the SCP\_BL2 key.
- **SCP\_BL2 content certificate**
It is self-signed with the SCP\_BL2 key. It contains a hash of the SCP\_BL2
image.
- **BL31 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL31 key.
- **BL31 content certificate**
It is self-signed with the BL31 key. It contains a hash of the BL31 image.
- **BL32 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL32 key.
- **BL32 content certificate**
It is self-signed with the BL32 key. It contains a hash of the BL32 image.
- **BL33 key certificate**
It is self-signed with the non-trusted world key. It contains the public
part of the BL33 key.
- **BL33 content certificate**
It is self-signed with the BL33 key. It contains a hash of the BL33 image.
The SCP\_BL2 and BL32 certificates are optional, but they must be present if the
corresponding SCP\_BL2 or BL32 images are present.
Trusted Board Boot Sequence
---------------------------
The CoT is verified through the following sequence of steps. The system panics
if any of the steps fail.
- BL1 loads and verifies the BL2 content certificate. The issuer public key is
read from the verified certificate. A hash of that key is calculated and
compared with the hash of the ROTPK read from the trusted root-key storage
registers. If they match, the BL2 hash is read from the certificate.
Note: the matching operation is platform specific and is currently
unimplemented on the ARM development platforms.
- BL1 loads the BL2 image. Its hash is calculated and compared with the hash
read from the certificate. Control is transferred to the BL2 image if all
the comparisons succeed.
- BL2 loads and verifies the trusted key certificate. The issuer public key is
read from the verified certificate. A hash of that key is calculated and
compared with the hash of the ROTPK read from the trusted root-key storage
registers. If the comparison succeeds, BL2 reads and saves the trusted and
non-trusted world public keys from the verified certificate.
The next two steps are executed for each of the SCP\_BL2, BL31 & BL32 images.
The steps for the optional SCP\_BL2 and BL32 images are skipped if these images
are not present.
- BL2 loads and verifies the BL3x key certificate. The certificate signature
is verified using the trusted world public key. If the signature
verification succeeds, BL2 reads and saves the BL3x public key from the
certificate.
- BL2 loads and verifies the BL3x content certificate. The signature is
verified using the BL3x public key. If the signature verification succeeds,
BL2 reads and saves the BL3x image hash from the certificate.
The next two steps are executed only for the BL33 image.
- BL2 loads and verifies the BL33 key certificate. If the signature
verification succeeds, BL2 reads and saves the BL33 public key from the
certificate.
- BL2 loads and verifies the BL33 content certificate. If the signature
verification succeeds, BL2 reads and saves the BL33 image hash from the
certificate.
The next step is executed for all the boot loader images.
- BL2 calculates the hash of each image. It compares it with the hash obtained
from the corresponding content certificate. The image authentication succeeds
if the hashes match.
The Trusted Board Boot implementation spans both generic and platform-specific
BL1 and BL2 code, and in tool code on the host build machine. The feature is
enabled through use of specific build flags as described in the `User Guide`_.
On the host machine, a tool generates the certificates, which are included in
the FIP along with the boot loader images. These certificates are loaded in
Trusted SRAM using the IO storage framework. They are then verified by an
Authentication module included in the Trusted Firmware.
The mechanism used for generating the FIP and the Authentication module are
described in the following sections.
Authentication Framework
------------------------
The authentication framework included in the Trusted Firmware provides support
to implement the desired trusted boot sequence. ARM platforms use this framework
to implement the boot requirements specified in the TBBR-client document.
More information about the authentication framework can be found in the
`Auth Framework`_ document.
Certificate Generation Tool
---------------------------
The ``cert_create`` tool is built and runs on the host machine as part of the
Trusted Firmware build process when ``GENERATE_COT=1``. It takes the boot loader
images and keys as inputs (keys must be in PEM format) and generates the
certificates (in DER format) required to establish the CoT. New keys can be
generated by the tool in case they are not provided. The certificates are then
passed as inputs to the ``fiptool`` utility for creating the FIP.
The certificates are also stored individually in the in the output build
directory.
The tool resides in the ``tools/cert_create`` directory. It uses OpenSSL SSL
library version 1.0.1 or later to generate the X.509 certificates. Instructions
for building and using the tool can be found in the `User Guide`_.
--------------
*Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.*
.. _Firmware Update: firmware-update.rst
.. _X.509 v3: http://www.ietf.org/rfc/rfc5280.txt
.. _User Guide: user-guide.rst
.. _Auth Framework: auth-framework.rst
Reference in New Issue View Git Blame Copy Permalink