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

docs/porting-guide.md

@@ -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

docs/trusted-board-boot.md

+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

docs/user-guide.md

@@ -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