1Building FIP images with support for Trusted Board Boot
2=======================================================
3
4Trusted Board Boot primarily consists of the following two features:
5
6-  Image Authentication, described in :ref:`Trusted Board Boot`, and
7-  Firmware Update, described in :ref:`Firmware Update (FWU)`
8
9The following steps should be followed to build FIP and (optionally) FWU_FIP
10images with support for these features:
11
12#. Fulfill the dependencies of the ``mbedtls`` cryptographic and image parser
13   modules by checking out a recent version of the `mbed TLS Repository`_. It
14   is important to use a version that is compatible with TF-A and fixes any
15   known security vulnerabilities. See `mbed TLS Security Center`_ for more
16   information. See the :ref:`Prerequisites` document for the appropriate
17   version of mbed TLS to use.
18
19   The ``drivers/auth/mbedtls/mbedtls_*.mk`` files contain the list of mbed TLS
20   source files the modules depend upon.
21   ``include/drivers/auth/mbedtls/mbedtls_config.h`` contains the configuration
22   options required to build the mbed TLS sources.
23
24   Note that the mbed TLS library is licensed under the Apache version 2.0
25   license. Using mbed TLS source code will affect the licensing of TF-A
26   binaries that are built using this library.
27
28#. To build the FIP image, ensure the following command line variables are set
29   while invoking ``make`` to build TF-A:
30
31   -  ``MBEDTLS_DIR=<path of the directory containing mbed TLS sources>``
32   -  ``TRUSTED_BOARD_BOOT=1``
33   -  ``GENERATE_COT=1``
34
35   By default, this will use the Chain of Trust described in the TBBR-client
36   document. To select a different one, use the ``COT`` build option.
37
38   In the case of Arm platforms, the location of the ROTPK hash must also be
39   specified at build time. The following locations are currently supported (see
40   ``ARM_ROTPK_LOCATION`` build option):
41
42   -  ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted
43      root-key storage registers present in the platform. On Juno, these
44      registers are read-only. On FVP Base and Cortex models, the registers
45      are also read-only, but the value can be specified using the command line
46      option ``bp.trusted_key_storage.public_key`` when launching the model.
47      On Juno board, the default value corresponds to an ECDSA-SECP256R1 public
48      key hash, whose private part is not currently available.
49
50   -  ``ARM_ROTPK_LOCATION=devel_rsa``: use the default hash located in
51      ``plat/arm/board/common/rotpk/arm_rotpk_rsa_sha256.bin``. Enforce
52      generation of the new hash if ``ROT_KEY`` is specified.
53
54   -  ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the default hash located in
55      ``plat/arm/board/common/rotpk/arm_rotpk_ecdsa_sha256.bin``. Enforce
56      generation of the new hash if ``ROT_KEY`` is specified.
57
58   Example of command line using RSA development keys:
59
60   .. code:: shell
61
62       MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
63       make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1        \
64       ARM_ROTPK_LOCATION=devel_rsa                                    \
65       ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
66       BL33=<path-to>/<bl33_image>                                     \
67       all fip
68
69   The result of this build will be the bl1.bin and the fip.bin binaries. This
70   FIP will include the certificates corresponding to the selected Chain of
71   Trust. These certificates can also be found in the output build directory.
72
73#. The optional FWU_FIP contains any additional images to be loaded from
74   Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the
75   FWU_FIP, any FWU images required by the platform must be specified on the
76   command line. On Arm development platforms like Juno, these are:
77
78   -  NS_BL2U. The AP non-secure Firmware Updater image.
79   -  SCP_BL2U. The SCP Firmware Update Configuration image.
80
81   Example of Juno command line for generating both ``fwu`` and ``fwu_fip``
82   targets using RSA development:
83
84   ::
85
86       MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
87       make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1              \
88       ARM_ROTPK_LOCATION=devel_rsa                                    \
89       ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
90       BL33=<path-to>/<bl33_image>                                     \
91       SCP_BL2=<path-to>/<scp_bl2_image>                               \
92       SCP_BL2U=<path-to>/<scp_bl2u_image>                             \
93       NS_BL2U=<path-to>/<ns_bl2u_image>                               \
94       all fip fwu_fip
95
96   .. note::
97      The BL2U image will be built by default and added to the FWU_FIP.
98      The user may override this by adding ``BL2U=<path-to>/<bl2u_image>``
99      to the command line above.
100
101   .. note::
102      Building and installing the non-secure and SCP FWU images (NS_BL1U,
103      NS_BL2U and SCP_BL2U) is outside the scope of this document.
104
105   The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
106   Both the FIP and FWU_FIP will include the certificates corresponding to the
107   selected Chain of Trust. These certificates can also be found in the output
108   build directory.
109
110--------------
111
112*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
113
114.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
115.. _mbed TLS Security Center: https://tls.mbed.org/security
116