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
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:
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
--- /dev/null
+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
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:
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
[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
projects / project / bcm63xx / atf.git / commitdiff