1###########################################
2Trusted Firmware-M Profile Medium-ARoT-less
3###########################################
4
5************
6Introduction
7************
8
9TF-M Profile Medium-ARoT-less is a reference implementation to align with security requirements
10defined in PSA Certified ARoT-less Level 2 protection profile (PSA Certified ARoT-less) [1]_.
11
12TF-M Profile Medium-ARoT-less is defined based on TF-M Profile Medium [2]_, which aligns with PSA
13Certified Level 2 Protection Profile [3]_.
14
15**************
16Overall design
17**************
18
19TF-M Profile Medium-ARoT-less defines the following feature set:
20
21    - Firmware Framework
22
23        - Secure Function (SFN) model [4]_
24        - Isolation level 1 [5]_
25
26    - Internal Trusted Storage (ITS)
27
28    - Crypto
29
30        - Support both symmetric cryptography and asymmetric cryptography
31        - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for
32          IoT [6]_ and CoAP [7]_, including
33
34            - Authenticated Encryption with Associated Data (AEAD) algorithm
35            - Asymmetric key algorithm based signature and verification
36            - Public-key cryptography based key exchange
37            - Hash function
38            - HMAC for default Pseudorandom Function (PRF)
39
40        - Asymmetric digital signature and verification for Initial Attestation
41          Token (IAT)
42
43    - Initial Attestation
44
45        - Asymmetric key algorithm based Initial Attestation
46
47    - Lightweight boot
48
49        - Anti-rollback protection
50        - Multiple image boot
51
52    - Firmware Update (FWU) RoT Service
53
54**************
55Design details
56**************
57
58Most of design in Profile Medium-ARoT-less is identical to that in Profile Medium. Refer to
59Profile Medium document [2]_ for details.
60Only the differences between Profile Medium-ARoT-less and Profile Medium are specified below.
61
62Firmware framework
63==================
64
65PSA Certified ARoT-less [1]_ is only applicable to devices that don’t support Application RoT (ARoT)
66services.
67The platform only consists of PSA RoT domain(s) in SPE making it unnecessary to implement the
68isolation between ARoT and PSA RoT.
69Therefore, this profile selects isolation level 1 to simplify implementation and optimize memory
70footprint and performance.
71
72Since only isolation level 1 is required, this profile enables SFN model rather than IPC mode for
73further simplification.
74
75Protected Storage
76=================
77
78Protected Storage (PS) is implemented as an Application RoT service in TF-M by default.
79Therefore, PS is disabled by default in this profile.
80
81FWU RoT Service
82===============
83
84As PSA Certified ARoT-less requests, FWU RoT Service is enabled by default to support secure
85update of platform if the platform supports FWU.
86
87.. note ::
88
89    **Implementation note**
90
91    The entire secure update sequence involves multiple agents and components, including bootloader,
92    TF-M FWU RoT Service, image update application(s), remote server(s), etc.
93
94    The secure update sequence is implementation-defined. Here is a reference of TF-M integration
95    with FreeRTOS OTA [8]_.
96
97**************
98Implementation
99**************
100
101The basic idea is to add dedicated profile CMake configuration files
102``config/profile/profile_medium_arotless`` for this profile default configuration.
103
104This top-level config file collects all the fundamental configuration flags and set them to default
105values, to explicitly configured the features required in this profile, during TF-M build.
106
107A platform/use case overwrite the default settings to configure this profile.
108
109The behavior of the build flow (particularly the order of configuration loading and overriding) can
110be found at :ref:`tfm_cmake_configuration`.
111
112The default configurations in ``config/profile/profile_medium_arotless`` are shown below.
113
114.. table:: Config flags in Profile Medium-ARoT-less top-level CMake config file
115   :widths: auto
116   :align: center
117
118   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
119   | Configs                                    | Default value                                                                                       | Descriptions                        |
120   +============================================+=====================================================================================================+=====================================+
121   | ``TFM_ISOLATION_LEVEL``                    | ``1``                                                                                               | Select level 1 isolation            |
122   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
123   | ``CONFIG_TFM_SPM_BACKEND``                 | ``SFN``                                                                                             | Select SFN model                    |
124   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
125   | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON``                                                                                              | Enable ITS SP                       |
126   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
127   | ``ITS_BUF_SIZE``                           | ``32``                                                                                              | ITS internal transient buffer size  |
128   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
129   | ``TFM_PARTITION_CRYPTO``                   | ``ON``                                                                                              | Enable Crypto service               |
130   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
131   | ``CRYPTO_ASYM_ENCRYPT_MODULE_ENABLED``     | ``OFF``                                                                                             | Enable Crypto asymmetric            |
132   |                                            |                                                                                                     | encryption operations               |
133   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
134   | ``TFM_MBEDCRYPTO_CONFIG_PATH``             | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Re-use Profile Medium configuration |
135   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
136   | ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``  | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_medium.h``         | Re-use Profile Medium configuration |
137   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
138   | ``TFM_PARTITION_INITIAL_ATTESTATION``      | ``ON``                                                                                              | Enable Initial Attestation service  |
139   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
140   | ``TFM_PARTITION_FIRMWARE_UPDATE``          | ``ON``                                                                                              | Enable Firmware Update service      |
141   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
142   | ``TFM_PARTITION_PROTECTED_STORAGE``        | ``OFF``                                                                                             | Disable PS service                  |
143   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
144   | ``TFM_PARTITION_PLATFORM``                 | ``ON``                                                                                              | Enable TF-M Platform SP             |
145   +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+
146
147.. note::
148
149   Where a configuration is the same as the default in
150   ``config/config_default.cmake``, it might be omitted from the profile configuration
151   file.
152
153.. note::
154
155    **Implementation note**
156
157    If the platform doesn't support secure update functionalities, FWU service will be disabled
158    automatically. A warning will be thrown out during build.
159
160Regression test configuration
161=============================
162
163FWU regression tests and SFN regression tests are selected by default when regression tests are
164enabled.
165Other implementations are the same as those in Profile Medium.
166
167****************
168Platform support
169****************
170
171To enable Profile Medium on a platform, the platform specific CMake file should
172be added into the platform support list in top-level Profile Medium CMake config
173file.
174
175Building Profile Medium
176=======================
177
178To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be
179set to ``profile_medium_arotless``.
180
181Take Musca-B1 as an example.
182The following commands build Profile Medium without test cases on **Musca-B1** with
183build type **MinSizeRel**, built by **Armclang**.
184
185.. code-block:: bash
186
187   cd <TFM root dir>
188   mkdir build && cd build
189   cmake -DTFM_PLATFORM=musca-b1 \
190         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
191         -DTFM_PROFILE=profile_medium_arotless \
192         -DCMAKE_BUILD_TYPE=MinSizeRel \
193         ../
194   cmake --build ./ -- install
195
196The following commands build Profile Medium-ARoT-less with regression test cases on
197**Musca-B1** with build type **MinSizeRel**, built by **Armclang**.
198
199.. code-block:: bash
200
201   cd <TFM root dir>
202   mkdir build && cd build
203   cmake -DTFM_PLATFORM=musca-b1 \
204         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
205         -DTFM_PROFILE=profile_medium_arotless \
206         -DCMAKE_BUILD_TYPE=MinSizeRel \
207         -DTEST_S=ON -DTEST_NS=ON \
208         ../
209   cmake --build ./ -- install
210
211.. note::
212
213 - For devices with more constrained memory and flash requirements, it is
214   possible to build with either only TEST_S enabled or only TEST_NS enabled.
215   This will decrease the size of the test images. Note that both test suites
216   must still be run to ensure correct operation.
217
218More details of building instructions and parameters can be found TF-M build instruction guide [9]_.
219
220*********
221Reference
222*********
223
224.. [1] `SESIP Profile for PSA Certified ARoT-less Level 2 <https://www.psacertified.org/app/uploads/2022/10/JSADEN019-PSA_Certified_Level_2_PP_SESIP_ARoT-less_REL-01.pdf>`_
225
226.. [2] :doc:`Trusted Firmware-M Profile Medium Design </configuration/profiles/tfm_profile_medium>`
227
228.. [3] `SESIP Profile for PSA Certified Level 2 <https://www.psacertified.org/app/uploads/2021/03/JSADEN012-PSA_Certified_Level_2_PP_SESIP-BETA02.pdf>`_
229
230.. [4] `Arm Firmware Framework for M 1.1 Extensions <https://developer.arm.com/documentation/aes0039/latest>`_
231
232.. [5] `Arm Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/documentation/den0063/latest/>`_
233
234.. [6] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things <https://tools.ietf.org/html/rfc7925>`_
235
236.. [7] `The Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7252>`_
237
238.. [8] `Secure OTA Updates for Cortex-M Devices with FreeRTOS <https://www.freertos.org/2021/07/secure-ota-updates-for-cortex-m-devices-with-freertos.html>`_
239
240.. [9] :doc:`TF-M build instruction </building/tfm_build_instruction>`
241
242--------------
243
244*Copyright (c) 2020-2023, Arm Limited. All rights reserved.*
245