andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

TBB: Add documentation for Trusted Board Boot 

This patch updates the user-guide.md with the various build options related to
Trusted Board Boot and steps to build a FIP image which includes this
support. It also adds a trusted-board-boot.md which describes the scope and
design of this feature.

Change-Id: Ifb421268ebf7e06a135684c8ebb04c94835ce061
This commit is contained in:
Achin Gupta 2015-01-25 22:44:23 +00:00 committed by Juan Castillo
parent 8d6623bf68
commit 8d35f61bf2
3 changed files with 422 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
docs/porting-guide.md
View File

@ -126,6 +126,36 @@ file is found in [plat/fvp/include/platform_def.h].
Name of the BL3-3 binary image on the host file-system. This name is used by
BL2 to load BL3-3 into non-secure memory from platform storage.
* **#define : BL2_CERT_NAME**
Name of the BL2 content certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : TRUSTED_KEY_CERT_NAME**
Name of the Trusted Key certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : BL31_KEY_CERT_NAME**
Name of the BL3-1 Key certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : BL31_CERT_NAME**
Name of the BL3-1 Content certificate on the host file-system (mandatory
when Trusted Board Boot is enabled).
* **#define : BL33_KEY_CERT_NAME**
Name of the BL3-3 Key certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : BL33_CERT_NAME**
Name of the BL3-3 Content certificate on the host file-system (mandatory
when Trusted Board Boot is enabled).
* **#define : PLATFORM_CACHE_LINE_SIZE**
Defines the size (in bytes) of the largest cache line across all the cache
@ -194,6 +224,25 @@ file is found in [plat/fvp/include/platform_def.h].
Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary
image. Must be aligned on a page-size boundary.
If a BL3-0 image is supported by the platform, the following constants must
also be defined:
* **#define : BL30_IMAGE_NAME**
Name of the BL3-0 binary image on the host file-system. This name is used by
BL2 to load BL3-0 into secure memory from platform storage before being
transfered to the SCP.
* **#define : BL30_KEY_CERT_NAME**
Name of the BL3-0 Key certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : BL30_CERT_NAME**
Name of the BL3-0 Content certificate on the host file-system (mandatory
when Trusted Board Boot is enabled).
If a BL3-2 image is supported by the platform, the following constants must
also be defined:
@ -202,6 +251,16 @@ also be defined:
Name of the BL3-2 binary image on the host file-system. This name is used by
BL2 to load BL3-2 into secure memory from platform storage.
* **#define : BL32_KEY_CERT_NAME**
Name of the BL3-2 Key certificate on the host file-system (mandatory when
Trusted Board Boot is enabled).
* **#define : BL32_CERT_NAME**
Name of the BL3-2 Content certificate on the host file-system (mandatory
when Trusted Board Boot is enabled).
* **#define : BL32_BASE**
Defines the base address in secure memory where BL2 loads the BL3-2 binary

261
docs/trusted-board-boot.md Normal file
View File

@ -0,0 +1,261 @@
Trusted Board Boot Design Guide
===============================
Contents :
1. [Introduction](#1--introduction)
2. [Chain of Trust](#2--chain-of-trust)
3. [Trusted Board Boot Sequence](#3--trusted-board-boot-sequence)
4. [Authentication Module](#4--authentication-module)
5. [Certificate Generation Tool](#5--certificate-generation-tool)
1. Introduction
----------------
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 the ARM Trusted Firmware TBB
implementation. The current implementation is a proof of concept; future
versions will provide stronger architectural interfaces and implement the
missing functionality required in a production TBB-enabled system.
2. 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-1 with RSA Encryption
signature scheme is used with a RSA key length of 2048 bits. Future version of
Trusted Firmware will replace SHA-1 usage with SHA-256 and 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 (BL3-0, BL3-1 and BL3-2). 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 (BL3-3). The public part is stored in one of the
extension fields in the trusted world certificate.
* **BL3-X keys**
For each of BL3-0, BL3-1, BL3-2 and BL3-3, 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
* BL3-0 (optional)
* BL3-1
* BL3-3
* BL3-2 (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.
* **BL3-0 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL3-0 key.
* **BL3-0 content certificate**
It is self-signed with the BL3-0 key. It contains a hash of the BL3-0 image.
* **BL3-1 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL3-1 key.
* **BL3-1 content certificate**
It is self-signed with the BL3-1 key. It contains a hash of the BL3-1 image.
* **BL3-2 key certificate**
It is self-signed with the trusted world key. It contains the public part of
the BL3-2 key.
* **BL3-2 content certificate**
It is self-signed with the BL3-2 key. It contains a hash of the BL3-2 image.
* **BL3-3 key certificate**
It is self-signed with the non-trusted world key. It contains the public
part of the BL3-3 key.
* **BL3-3 content certificate**
It is self-signed with the BL3-3 key. It contains a hash of the BL3-3 image.
The BL3-0 and BL3-2 certificates are optional, but they must be present if the
corresponding BL3-0 or BL3-2 images are present.
3. 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 BL3-0, BL3-1 & BL3-2 images. The
steps for the optional BL3-0 and BL3-2 images are skipped if these images are
not present.
* BL2 loads and verifies the BL3-x key certificate. The certificate signature
is verified using the trusted world public key. If the signature
verification succeeds, BL2 reads and saves the BL3-x public key from the
certificate.
* BL2 loads and verifies the BL3-x content certificate. The signature is
verified using the BL3-x public key. If the signature verification succeeds,
BL2 reads and saves the BL3-x image hash from the certificate.
The next two steps are executed only for the BL3-3 image.
* BL2 loads and verifies the BL3-3 key certificate. If the signature
verification succeeds, BL2 reads and saves the BL3-3 public key from the
certificate.
* BL2 loads and verifies the BL3-3 content certificate. If the signature
verification succeeds, BL2 reads and saves the BL3-3 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.
4. Authentication Module
-------------------------
The authentication module implements the required support to authenticate the
corresponding certificates or images at each step in the Trusted Board Boot
sequence. The module relies on the PolarSSL library (v1.3.9) to perform the
following operations:
* Parsing X.509 certificates and verifying them using SHA-1 with RSA
Encryption.
* Extracting public keys and hashes from the certificates.
* Generating hashes (SHA-256) of boot loader images
At each step, the module is responsible for allocating memory to store the
public keys or hashes that will be used in later steps. The step identifier is
used to determine what information must be saved, according to the CoT model
detailed in the previous sections.
The authentication module resides in the `common/auth/polarssl` directory.
Instructions for including the necessary modules of the PolarSSL SSL library and
building the authentication module can be found in the [User Guide].
5. 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 `fip_create` tool 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._
[X.509 v3]: http://www.ietf.org/rfc/rfc5280.txt
[X.690]: http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf
[User Guide]: user-guide.md

102
docs/user-guide.md
View File

@ -255,6 +255,64 @@ performed.
default model (when the value is 0) is to route non-secure interrupts
to S-EL1 (TSP).
* `TRUSTED_BOARD_BOOT`: Boolean flag to include support for the Trusted Board
Boot feature. When set to '1', BL1 and BL2 images include support to load
and verify the certificates and images in a FIP. The default value is '0'.
A successful build, when `TRUSTED_BOARD_BOOT=1`, depends upon the correct
initialization of the `AUTH_MOD` option. Generation and inclusion of
certificates in the FIP depends upon the value of the `GENERATE_COT` option.
* `AUTH_MOD`: This option is used when `TRUSTED_BOARD_BOOT=1`. It specifies
the name of the authentication module that will be used in the Trusted Board
Boot sequence. The module must be located in `common/auth/<module name>`
directory. The directory must contain a makefile `<module name>.mk` which
will be used to build the module. More information can be found in
[Trusted Board Boot]. The default module name is 'none'.
* `GENERATE_COT`: Boolean flag used to build and execute the `cert_create`
tool to create certificates as per the Chain of Trust described in
[Trusted Board Boot]. The build system then calls the `fip_create` tool to
include the certificates in the FIP. Default value is '0'.
Specify `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support for
the Trusted Board Boot Sequence in the BL1 and BL2 images and the FIP.
Note that if `TRUSTED_BOARD_BOOT=0` and `GENERATE_COT=1`, the BL1 and BL2
images will not include support for Trusted Board Boot. The FIP will still
include the key and content certificates. This FIP can be used to verify the
Chain of Trust on the host machine through other mechanisms.
Note that if `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=0`, the BL1 and BL2
images will include support for Trusted Board Boot, but the FIP will not
include the key and content certificates, causing a boot failure.
* `CREATE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the
certificate generation tool to create new keys in case no valid keys are
present or specified. Allowed options are '0' or '1'. Default is '1'.
* `ROT_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the ROT private key in PEM format.
* `TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It
specifies the file that contains the Trusted World private key in PEM
format.
* `NON_TRUSTED_WORLD_KEY`: This option is used when `GENERATE_COT=1`. It
specifies the file that contains the Non-Trusted World private key in PEM
format.
* `BL30_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-0 private key in PEM format.
* `BL31_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-1 private key in PEM format.
* `BL32_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-2 private key in PEM format.
* `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
file that contains the BL3-3 private key in PEM format.
#### FVP specific build options
* `FVP_TSP_RAM_LOCATION`: location of the TSP binary. Options:
@ -391,6 +449,48 @@ FVP_AARCH64_EFI.fd as BL3-3 image:
Creating "build/fvp/release/fip.bin"
### Building the Certificate Generation Tool
The `cert_create` tool can be built separately through the following commands:
$ cd tools/cert_create
$ make [DEBUG=1] [V=1]
`DEBUG=1` builds the tool in debug mode. `V=1` makes the build process more
verbose. The following command should be used to obtain help about the tool:
$ ./cert_create -h
The `cert_create` tool is automatically built with the `fip` target when
`GENERATE_COT=1`.
### Building a FIP image with support for Trusted Board Boot
The Trusted Board Boot feature is described in [Trusted Board Boot]. The
following steps should be followed to build a FIP image with support for this
feature.
1. Fulfill the dependencies of the `polarssl` authentication module by checking
out the tag `polarssl-1.3.9` from the [PolarSSL Repository].
The `common/auth/polarssl/polarssl.mk` contains the list of PolarSSL source
files the module depends upon. `common/auth/polarssl/polarssl_config.h`
contains the configuration options required to build the PolarSSL sources.
Note that the PolarSSL SSL library is licensed under the GNU GPL version 2
or later license. Using PolarSSL source code will affect the licensing of
Trusted Firmware binaries that are built using this library.
2. Ensure that the following command line variables are set while invoking
`make` to build Trusted Firmware:
* `POLARSSL_DIR=<path of the directory containing PolarSSL sources>`
* `AUTH_MOD=polarssl`
* `TRUSTED_BOARD_BOOT=1`
* `GENERATE_COT=1`
### Checking source code style
When making changes to the source for submission to the project, the source
@ -997,3 +1097,5 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
[Linaro Toolchain]: http://releases.linaro.org/14.07/components/toolchain/binaries/
[EDK2]: http://github.com/tianocore/edk2
[DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php
[Polarssl Repository]: https://github.com/polarssl/polarssl.git
[Trusted Board Boot]: trusted-board-boot.md