1TF-M Build System
2#################
3
4When building a valid ``_ns`` board target, TF-M will be built in the
5background, and linked with the Zephyr non-secure application. No knowledge
6of TF-M's build system is required in most cases, and the following will
7build a TF-M and Zephyr image pair, and run it in qemu with no additional
8steps required:
9
10   .. code-block:: bash
11
12     $ west build -p auto -t mps2_an521_ns samples/tfm_integration/psa_crypto/ -t run
13
14The outputs and certain key steps in this build process are described here,
15however, since you will need to understand and interact with the outputs, and
16deal with signing the secure and non-secure images before deploying them.
17
18Images Created by the TF-M Build
19********************************
20
21The TF-M build system creates the following executable files:
22
23* tfm_s - the secure firmware
24* tfm_ns - a nonsecure app which is discarded in favor of the Zephyr app
25* bl2 - mcuboot, if enabled
26
27For each of these, it creates .bin, .hex, .elf, and .axf files.
28
29The TF-M build system also creates signed variants of tfm_s and tfm_ns, and a
30file which combines them:
31
32* tfm_s_signed
33* tfm_ns_signed
34* tfm_s_ns_signed
35
36For each of these, only .bin files are created.
37
38The Zephyr build system usually signs both tfm_s and the Zephyr ns app itself.
39See below for details.
40
41The 'tfm' target contains properties for all these paths.
42For example, the following will resolve to ``<path>/tfm_s.hex``:
43
44   .. code-block::
45
46      $<TARGET_PROPERTY:tfm,TFM_S_HEX_FILE>
47
48See the top level CMakeLists.txt file in the tfm module for an overview of all
49the properties.
50
51Signing Images
52**************
53
54When :kconfig:`CONFIG_TFM_BL2` is set to ``y``, TF-M uses a secure bootloader
55(BL2) and firmware images must be signed with a private key. The firmware image
56is validated by the bootloader during updates using the corresponding public
57key, which is stored inside the secure bootloader firmware image.
58
59By default, ``tfm/bl2/ext/mcuboot/root-rsa-3072.pem`` is used to sign secure
60images, and ``tfm/bl2/ext/mcuboot/root-rsa-3072_1.pem`` is used to sign
61non-secure images. Theses default .pem keys can (and **should**) be overridden
62using the :kconfig:`CONFIG_TFM_KEY_FILE_S` and
63:kconfig:`CONFIG_TFM_KEY_FILE_NS` config flags.
64
65To satisfy `PSA Certified Level 1`_ requirements, **You MUST replace
66the default .pem file with a new key pair!**
67
68To generate a new public/private key pair, run the following commands:
69
70   .. code-block:: bash
71
72     $ imgtool keygen -k root-rsa-3072_s.pem -t rsa-3072
73     $ imgtool keygen -k root-rsa-3072_ns.pem -t rsa-3072
74
75You can then place the new .pem files in an alternate location, such as your
76Zephyr application folder, and reference them in the ``prj.conf`` file via the
77:kconfig:`CONFIG_TFM_KEY_FILE_S` and :kconfig:`CONFIG_TFM_KEY_FILE_NS` config
78flags.
79
80   .. warning::
81
82     Be sure to keep your private key file in a safe, reliable location! If you
83     lose this key file, you will be unable to sign any future firmware images,
84     and it will no longer be possible to update your devices in the field!
85
86After the built-in signing script has run, it creates a ``tfm_merged.hex``
87file that contains all three binaries: bl2, tfm_s, and the zephyr app. This
88hex file can then be flashed to your development board or run in QEMU.
89
90.. _PSA Certified Level 1:
91  https://www.psacertified.org/security-certification/psa-certified-level-1/
92
93Custom CMake arguments
94======================
95
96When building a Zephyr application with TF-M it might be necessary to control
97the CMake arguments passed to the TF-M build.
98
99Zephyr TF-M build offers several Kconfig options for controlling the build, but
100doesn't cover every CMake argument supported by the TF-M build system.
101
102The ``TFM_CMAKE_OPTIONS`` property on the ``zephyr_property_target`` can be used
103to pass custom CMake arguments to the TF-M build system.
104
105To pass the CMake argument ``-DFOO=bar`` to the TF-M build system, place the
106following CMake snippet in your CMakeLists.txt file.
107
108   .. code-block:: cmake
109
110     set_property(TARGET zephyr_property_target
111                  APPEND PROPERTY TFM_CMAKE_OPTIONS
112                  -DFOO=bar
113     )
114
115.. note::
116   The ``TFM_CMAKE_OPTIONS`` is a list so it is possible to append multiple
117   options. Also CMake generator expressions are supported, such as
118   ``$<1:-DFOO=bar>``
119