1Building Supporting Tools 2========================= 3 4.. note:: 5 6 OpenSSL 3.0 is needed in order to build the tools. A custom installation 7 can be used if not updating the OpenSSL version on the OS. In order to do 8 this, use the ``OPENSSL_DIR`` variable after the ``make`` command to 9 indicate the location of the custom OpenSSL build. Then, to run the tools, 10 use the ``LD_LIBRARY_PATH`` to indicate the location of the built 11 libraries. More info about ``OPENSSL_DIR`` can be found at 12 :ref:`Build Options`. 13 14Building and using the FIP tool 15------------------------------- 16 17Firmware Image Package (FIP) is a packaging format used by TF-A to package 18firmware images in a single binary. The number and type of images that should 19be packed in a FIP is platform specific and may include TF-A images and other 20firmware images required by the platform. For example, most platforms require 21a BL33 image which corresponds to the normal world bootloader (e.g. UEFI or 22U-Boot). 23 24The TF-A build system provides the make target ``fip`` to create a FIP file 25for the specified platform using the FIP creation tool included in the TF-A 26project. Examples below show how to build a FIP file for FVP, packaging TF-A 27and BL33 images. 28 29For AArch64: 30 31.. code:: shell 32 33 make PLAT=fvp BL33=<path-to>/bl33.bin fip 34 35For AArch32: 36 37.. code:: shell 38 39 make PLAT=fvp ARCH=aarch32 AARCH32_SP=sp_min BL33=<path-to>/bl33.bin fip 40 41The resulting FIP may be found in: 42 43:: 44 45 build/fvp/<build-type>/fip.bin 46 47For advanced operations on FIP files, it is also possible to independently build 48the tool and create or modify FIPs using this tool. To do this, follow these 49steps: 50 51It is recommended to remove old artifacts before building the tool: 52 53.. code:: shell 54 55 make -C tools/fiptool clean 56 57Build the tool: 58 59.. code:: shell 60 61 make [DEBUG=1] [V=1] fiptool 62 63The tool binary can be located in: 64 65:: 66 67 ./tools/fiptool/fiptool 68 69Invoking the tool with ``help`` will print a help message with all available 70options. 71 72Example 1: create a new Firmware package ``fip.bin`` that contains BL2 and BL31: 73 74.. code:: shell 75 76 ./tools/fiptool/fiptool create \ 77 --tb-fw build/<platform>/<build-type>/bl2.bin \ 78 --soc-fw build/<platform>/<build-type>/bl31.bin \ 79 fip.bin 80 81Example 2: view the contents of an existing Firmware package: 82 83.. code:: shell 84 85 ./tools/fiptool/fiptool info <path-to>/fip.bin 86 87Example 3: update the entries of an existing Firmware package: 88 89.. code:: shell 90 91 # Change the BL2 from Debug to Release version 92 ./tools/fiptool/fiptool update \ 93 --tb-fw build/<platform>/release/bl2.bin \ 94 build/<platform>/debug/fip.bin 95 96Example 4: unpack all entries from an existing Firmware package: 97 98.. code:: shell 99 100 # Images will be unpacked to the working directory 101 ./tools/fiptool/fiptool unpack <path-to>/fip.bin 102 103Example 5: remove an entry from an existing Firmware package: 104 105.. code:: shell 106 107 ./tools/fiptool/fiptool remove \ 108 --tb-fw build/<platform>/debug/fip.bin 109 110Note that if the destination FIP file exists, the create, update and 111remove operations will automatically overwrite it. 112 113The unpack operation will fail if the images already exist at the 114destination. In that case, use -f or --force to continue. 115 116More information about FIP can be found in the :ref:`Firmware Design` document. 117 118.. _tools_build_cert_create: 119 120Building the Certificate Generation Tool 121---------------------------------------- 122 123The ``cert_create`` tool is built as part of the TF-A build process when the 124``fip`` make target is specified and TBB is enabled (as described in the 125previous section), but it can also be built separately with the following 126command: 127 128.. code:: shell 129 130 make PLAT=<platform> [DEBUG=1] [V=1] certtool 131 132For platforms that require their own IDs in certificate files, the generic 133'cert_create' tool can be built with the following command. Note that the target 134platform must define its IDs within a ``platform_oid.h`` header file for the 135build to succeed. 136 137.. code:: shell 138 139 make PLAT=<platform> USE_TBBR_DEFS=0 [DEBUG=1] [V=1] certtool 140 141``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more 142verbose. The following command should be used to obtain help about the tool: 143 144.. code:: shell 145 146 ./tools/cert_create/cert_create -h 147 148.. _tools_build_enctool: 149 150Building the Firmware Encryption Tool 151~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 152 153The ``encrypt_fw`` tool is built as part of the TF-A build process when the 154``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but 155it can also be built separately with the following command: 156 157.. code:: shell 158 159 make PLAT=<platform> [DEBUG=1] [V=1] enctool 160 161``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more 162verbose. The following command should be used to obtain help about the tool: 163 164.. code:: shell 165 166 ./tools/encrypt_fw/encrypt_fw -h 167 168Note that the enctool in its current implementation only supports encryption 169key to be provided in plain format. A typical implementation can very well 170extend this tool to support custom techniques to protect encryption key. 171 172Also, a user may choose to provide encryption key or nonce as an input file 173via using ``cat <filename>`` instead of a hex string. 174 175-------------- 176 177*Copyright (c) 2019-2022, Arm Limited. All rights reserved.* 178