TBB: add authentication framework documentation

This patch updates the user guide, adding instructions to build the
Trusted Firmware with Trusted Board Support using the new framework.

It also provides documentation about the framework itself, including
a detailed section about the TBBR implementation using the framework.

Change-Id: I0849fce9c5294cd4f52981e7a8423007ac348ec6

docs/trusted-board-boot.md

@@ -6,7 +6,7 @@ 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)
+4.  [Authentication Framework](#4--authentication-framework)
 5.  [Certificate Generation Tool](#5--certificate-generation-tool)
 
 
@@ -209,27 +209,15 @@ The mechanism used for generating the FIP and the Authentication module are
 described in the following sections.
 
 
-4.  Authentication Module
--------------------------
+4.  Authentication Framework
+----------------------------
 
-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:
+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.
 
-*   Parsing X.509 certificates and verifying them using SHA-256 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].
+More information about the authentication framework can be found in the
+[Auth Framework] document.
 
 
 5.  Certificate Generation Tool
@@ -257,4 +245,5 @@ _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
+[Auth Framework]:    auth-framework.md
 [User Guide]:        user-guide.md

docs/user-guide.md

@@ -507,25 +507,58 @@ 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].
+1.  Fulfill the dependencies of the `mbedtls` cryptographic and image parser
+    modules by checking out the tag `mbedtls-1.3.11` from the
+    [mbedTLS 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.
+    The `drivers/auth/mbedtls/mbedtls_*.mk` files contain the list of mbedTLS
+    source files the modules depend upon.
+    `include/drivers/auth/mbedtls/mbedtls_config.h` contains the configuration
+    options required to build the mbedTLS 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
+    Note that the mbedTLS library is licensed under the GNU GPL version 2
+    or later license. Using mbedTLS 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`
+    *   `MBEDTLS_DIR=<path of the directory containing mbedTLS sources>`
     *   `TRUSTED_BOARD_BOOT=1`
     *   `GENERATE_COT=1`
 
+    In the case of ARM platforms, the location of the ROTPK hash must also be
+    specified at build time. Two locations are currently supported (see
+    `ARM_ROTPK_LOCATION` build option):
+
+    *   `ARM_ROTPK_LOCATION=regs`: the ROTPK hash is obtained from the Trusted
+        root-key storage registers present in the platform. On Juno, this
+        registers are read-only. On FVP Base and Cortex models, the registers
+        are read-only, but the value can be specified using the command line
+        option `bp.trusted_key_storage.public_key` when launching the model.
+        On both Juno and FVP models, the default value corresponds to an
+        ECDSA-SECP256R1 public key hash, whose private part is not currently
+        available.
+
+    *   `ARM_ROTPK_LOCATION=devel_rsa`: use the ROTPK hash that is hardcoded
+        in the ARM platform port. The private/public RSA key pair may be
+        found in `plat/arm/board/common/rotpk`.
+
+    Example of command line using RSA development keys:
+
+        CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-       \
+        BL33=<path-to>/<bl33_image>                                     \
+        MBEDTLS_DIR=<path of the directory containing mbedTLS sources>  \
+        make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1        \
+        ARM_ROTPK_LOCATION=devel_rsa                                    \
+        ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
+        all fip
+
+    The result of this build will be the bl1.bin and the fip.bin binaries, with
+    the difference that the FIP will include the certificates corresponding to
+    the Chain of Trust described in the TBBR-client document. These certificates
+    can also be found in the output build directory.
+
 
 ### Checking source code style
 
@@ -1145,5 +1178,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
+[mbedTLS Repository]:          https://github.com/ARMmbed/mbedtls.git
 [Trusted Board Boot]:          trusted-board-boot.md