diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 5a04c54..3ba6715 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -126,6 +126,36 @@ 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 @@ 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 @@ 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 diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md new file mode 100644 index 0000000..abba030 --- /dev/null +++ b/docs/trusted-board-boot.md @@ -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 diff --git a/docs/user-guide.md b/docs/user-guide.md index ab443ba..fde8827 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -255,6 +255,64 @@ 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/` + directory. The directory must contain a makefile `.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 @@ 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=` + * `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 @@ [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