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 - ``TRUSTED_BOARD_BOOT=1`` 32 - ``GENERATE_COT=1`` 33 34 By default, this will use the Chain of Trust described in the TBBR-client 35 document. To select a different one, use the ``COT`` build option. 36 37 If using a custom build of OpenSSL, set the ``OPENSSL_DIR`` variable 38 accordingly so it points at the OpenSSL installation path, as explained in 39 :ref:`Build Options`. In addition, set the ``LD_LIBRARY_PATH`` variable 40 when running to point at the custom OpenSSL path, so the OpenSSL libraries 41 are loaded from that path instead of the default OS path. Export this 42 variable if necessary. 43 44 In the case of Arm platforms, the location of the ROTPK must also be 45 specified at build time. The following locations are currently supported (see 46 ``ARM_ROTPK_LOCATION`` build option): 47 48 - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted 49 root-key storage registers present in the platform. On Juno, these 50 registers are read-only. On FVP Base and Cortex models, the registers 51 are also read-only, but the value can be specified using the command line 52 option ``bp.trusted_key_storage.public_key`` when launching the model. 53 On Juno board, the default value corresponds to an ECDSA-SECP256R1 public 54 key hash, whose private part is not currently available. 55 56 - ``ARM_ROTPK_LOCATION=devel_rsa``: the ROTPK is a hash of the 57 RSA public key corresponding to the private key specified by 58 ``ROT_KEY``. If ``ROT_KEY`` is not specified, the private key is 59 the development key ``plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem``. 60 There are also 3k and 4k RSA development keys in ``plat/arm/board/common/rotpk/``. 61 The hashing algorithm is selected by ``HASH_ALG``; sha256 is used if 62 ``HASH_ALG`` is not specified. 63 64 - ``ARM_ROTPK_LOCATION=devel_ecdsa``: the ROTPK is a hash of the 65 ECDSA public key corresponding to the private key specified by 66 ``ROT_KEY``. If ``ROT_KEY`` is not specified, the private key is 67 the development key ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem`` by default, 68 a 384 bit key ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa_secp384r1.pem`` also exists, 69 and can be specified by ``ROT_KEY``. The hashing algorithm is selected by ``HASH_ALG``; 70 sha256 is used if ``HASH_ALG`` is not specified. 71 72 - ``ARM_ROTPK_LOCATION=devel_full_dev_rsa_key``: the ROTPK is an unhashed 73 RSA public key corresponding to the private key specified by ``ROT_KEY``. 74 If ``ROT_KEY`` is not specified, the private key is the development key 75 ``plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem``. There are also 76 3k and 4k RSA development keys in ``plat/arm/board/common/rotpk/``. 77 78 - ``ARM_ROTPK_LOCATION=devel_full_dev_ecdsa_key``: the ROTPK is an unhashed 79 RSA public key corresponding to the private key specified by ``ROT_KEY``. 80 If ``ROT_KEY`` is not specified, the private key is the development key 81 ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa.pem``, a 384 bit key 82 ``plat/arm/board/common/rotpk/arm_rotprivk_ecdsa_secp384r1.pem`` also exists, 83 and can be specified by ``ROT_KEY``. 84 85 Example of command line using RSA development keys: 86 87 .. code:: shell 88 89 make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ 90 ARM_ROTPK_LOCATION=devel_rsa \ 91 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 92 BL33=<path-to>/<bl33_image> OPENSSL_DIR=<path-to>/<openssl> \ 93 all fip 94 95 The result of this build will be the bl1.bin and the fip.bin binaries. This 96 FIP will include the certificates corresponding to the selected Chain of 97 Trust. These certificates can also be found in the output build directory. 98 99#. The optional FWU_FIP contains any additional images to be loaded from 100 Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the 101 FWU_FIP, any FWU images required by the platform must be specified on the 102 command line. On Arm development platforms like Juno, these are: 103 104 - NS_BL2U. The AP non-secure Firmware Updater image. 105 - SCP_BL2U. The SCP Firmware Update Configuration image. 106 107 Example of Juno command line for generating both ``fwu`` and ``fwu_fip`` 108 targets using RSA development: 109 110 :: 111 112 make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1 \ 113 ARM_ROTPK_LOCATION=devel_rsa \ 114 ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem \ 115 BL33=<path-to>/<bl33_image> OPENSSL_DIR=<path-to>/<openssl> \ 116 SCP_BL2=<path-to>/<scp_bl2_image> \ 117 SCP_BL2U=<path-to>/<scp_bl2u_image> \ 118 NS_BL2U=<path-to>/<ns_bl2u_image> \ 119 all fip fwu_fip 120 121 .. note:: 122 The BL2U image will be built by default and added to the FWU_FIP. 123 The user may override this by adding ``BL2U=<path-to>/<bl2u_image>`` 124 to the command line above. 125 126 .. note:: 127 Building and installing the non-secure and SCP FWU images (NS_BL1U, 128 NS_BL2U and SCP_BL2U) is outside the scope of this document. 129 130 The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. 131 Both the FIP and FWU_FIP will include the certificates corresponding to the 132 selected Chain of Trust. These certificates can also be found in the output 133 build directory. 134 135-------------- 136 137*Copyright (c) 2019-2024, Arm Limited. All rights reserved.* 138 139.. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git 140.. _mbed TLS Security Center: https://tls.mbed.org/security 141