1#######################################
2Trusted Firmware-M Profile Large Design
3#######################################
4
5************
6Introduction
7************
8
9As one of TF-M Profiles, Profile Large protects less resource-constrained Arm
10Cortex-M devices.
11
12Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to
13enable more secure features to support higher level of security required in more
14complex usage scenarios.
15
16    - Isolation level 3 enables additional isolation between
17      :term:`Application RoT` (App RoT) services.
18    - More crypto algorithms and cipher suites are selected to securely connect
19      devices to remote services offered by various major Cloud Service
20      Providers (CSP)
21    - Basic software countermeasures against physical attacks can be enabled.
22
23Profile Large can be aligned as a reference implementation with the requirements
24defined in PSA Certified Level 3 Lightweight Protection Profile [3]_.
25
26**************
27Overall design
28**************
29
30TF-M Profile Large defines the following feature set:
31
32    - Firmware Framework
33
34        - Inter-Process Communication (IPC) model [4]_
35        - Isolation level 3 [4]_
36
37    - Internal Trusted Storage (ITS)
38
39    - Crypto
40
41        - Support both symmetric ciphers and asymmetric ciphers
42        - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support
43          direct secure connection to major CSPs, including
44
45            - Authenticated Encryption with Associated Data (AEAD) algorithm
46            - Asymmetric key algorithm based signature and verification
47            - Public-key cryptography based key exchange
48            - Hash function
49            - HMAC for default Pseudorandom Function (PRF)
50
51        - Asymmetric digital signature and verification for Initial Attestation
52          Token (IAT)
53        - Asymmetric algorithms for firmware image signature verification
54        - Key derivation
55
56    - Initial Attestation
57
58        - Asymmetric key algorithm based Initial Attestation
59
60    - Secure boot
61        - Anti-rollback protection
62        - Multiple image boot
63
64    - Protected Storage (PS) if off-chip storage device is integrated
65
66        - Data confidentiality
67        - Data integrity
68        - Rollback protection
69
70    - Software countermeasures against physical attacks
71
72**************
73Design details
74**************
75
76More details of TF-M Profile Large design are described in following sections.
77
78Firmware framework
79==================
80
81Profile Large selects IPC model and isolation level 3 by default.
82
83Isolation level 3 supports additional isolation between App RoT services,
84compared to isolation level 2. It can protect :term:`RoT` services from each
85other when their vendors don't trust each other.
86
87Crypto service
88==============
89
90Profile Large supports direct connection to Cloud services via common protocols,
91such as TLS 1.2.
92
93In some usage scenarios, PSA RoT can be managed by device manufacturer or other
94vendors and is out of control of application developers.
95Profile Large selects alternative crypto algorithms for each crypto function to
96support multiple common cipher suites required by various major CSPs. Therefore,
97application developers can support services for diverse CSPs on same devices
98with Profile Large, without relying on PSA RoT upgrades of crypto.
99
100Devices meeting Profile Large should be in a position to offer at least two
101alternatives to every cryptographic primitive for symmetric, asymmetric and
102hash, and be able to use them for encryption, AEAD, signature and verification.
103
104It will cost more resource in Profile Large to support more crypto algorithms
105and cipher suites, compared to Profile Medium [2]_.
106
107Boot loader
108===========
109
110BL2 implementation can be device specific. Devices may implement diverse
111boot processes with different features and configurations.
112However, the boot loader must support anti-rollback protection. Boot loader must
113be able to prevent unauthorized rollback, to protect devices from being
114downgraded to earlier versions with known vulnerabilities.
115
116MCUBoot in TF-M is configured as multiple image boot by default in Profile
117Large. In multiple image boot, secure and non-secure images can be signed
118independently with different keys and they can be updated separately. It can
119support multiple vendors scenarios, in which non-secure and secure images are
120generated and updated by different vendors.
121Multiple image boot may cost larger memory footprint compared with single image
122boot.
123
124Boot loader can implement software countermeasures to mitigate physical attacks.
125
126Protected Storage
127=================
128
129PS service is required if an off-chip storage device is integrated and used on
130the platform.
131
132Anti-rollback protection in PS relies on non-volatile counter(s) provided by
133TF-M Platform :term:`Secure Partition` (SP).
134
135Software countermeasures against physical attacks
136=================================================
137
138TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile
139Medium by default. It enables the following countermeasure techniques:
140
141    - Control flow monitor
142    - Failure loop hardening
143    - Complex constants
144    - Redundant variables and condition checks
145
146Refer to TF-M physical attack mitigation design document [6]_ for FIH library
147details.
148
149.. note ::
150
151    **TF-M FIH library is still under development**.
152
153    TF-M FIH library hardens TF-M critical execution steps to make physical
154    attacks more difficult, together with device hardware countermeasures.
155    It is not guaranteed that TF-M FIH library is able to mitigate all kinds of
156    physical attacks.
157
158.. note ::
159
160    **Implementation note**
161
162    TF-M FIH library doesn't cover platform specific critical configurations.
163    Platforms shall implement software countermeasures against physical attacks
164    to protect platform specific implementation.
165
166**************
167Implementation
168**************
169
170Overview
171========
172
173The basic idea is to add dedicated profile CMake configuration files under
174folder ``config/profile`` for TF-M Profile Large default configuration, the
175same as other TF-M Profiles do.
176
177The top-level Profile Large config file collects all the necessary configuration
178flags and set them to default values, to explicitly enable the features required
179in Profile Large and disable the unnecessary ones, during TF-M build.
180
181A platform/use case can provide a configuration extension file to overwrite
182Profile Large default setting and append other configurations.
183This configuration extension file can be added via parameter
184``TFM_EXTRA_CONFIG_PATH`` in build command line.
185
186The behaviour of the Profile Large build flow (particularly the order of
187configuration loading and overriding) can be found at
188:ref:`tfm_cmake_configuration`
189
190The details of configurations will be covered in each module in
191`Implementation details`_.
192
193Implementation details
194======================
195
196This section discusses the details of Profile Large implementation.
197
198Top-level configuration files
199-----------------------------
200
201The firmware framework configurations in ``config/profile/profile_large`` are
202shown below.
203
204.. table:: Config flags in Profile Large top-level CMake config file
205   :widths: auto
206   :align: center
207
208   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
209   | Configs                                    | Descriptions                       | Default value                                                                                      |
210   +============================================+====================================+====================================================================================================+
211   | ``TFM_ISOLATION_LEVEL``                    | Select level 3 isolation           | ``3``                                                                                              |
212   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
213   | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP                      | ``ON``                                                                                             |
214   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
215   | ``TFM_PARTITION_CRYPTO``                   | Enable Crypto service              | ``ON``                                                                                             |
216   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
217   | ``TFM_MBEDCRYPTO_CONFIG_PATH``             | MbedTLS config file path           | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` |
218   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
219   | ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``  | MbedTLS PSA config file path       | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_large.h``         |
220   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
221   | ``TFM_PARTITION_INITIAL_ATTESTATION``      | Enable Initial Attestation service | ``ON``                                                                                             |
222   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
223   | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_   | Enable PS service                  | ``ON``                                                                                             |
224   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
225   | ``TFM_PARTITION_PLATFORM``                 | Enable TF-M Platform SP            | ``ON``                                                                                             |
226   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
227
228.. [a] PS service is enabled by default. Platforms without off-chip storage
229       devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
230       service. See `Protected Storage Secure Partition`_ for details.
231
232Crypto service configurations
233-----------------------------
234
235Crypto Secure Partition
236^^^^^^^^^^^^^^^^^^^^^^^
237
238TF-M Profile Large enables Crypto SP in top-level CMake config file and selects
239all the Crypto modules.
240
241MbedTLS configurations
242^^^^^^^^^^^^^^^^^^^^^^
243
244TF-M Profile Large adds a dedicated MbedTLS config file
245``tfm_mbedcrypto_config_profile_large.h`` and MbedTLS PSA config file
246``crypto_config_profile_large.h`` under
247``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one
248``tfm_mbedcrypto_config_default.h`` and ``crypto_config_default.h`` [7]_.
249
250Major MbedTLS configurations are set as listed below:
251
252    - Enable SHA256, SHA384 and SHA512
253    - Enable generic message digest wrappers
254    - Enable AES
255    - Enable CCM mode, GCM mode, CTR mode, CFB mode and CBC mode for symmetric ciphers
256    - Disable other modes for symmetric ciphers
257    - Enable ECDH
258    - Enable ECDSA
259    - Enable RSA
260    - Select ECC curve ``secp256r1`` and ``secp384r1``
261    - Enable HMAC-based key derivation function
262    - Other configurations required by selected option above
263
264A device/use case can append an extra config header to the Profile Large default
265MbedTLS config file to override the default settings. This can be done by
266setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the
267platform config file ``platform/ext<TFM_PLATFORM>/config.cmake``.
268This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE``
269options, but is preferred as it keeps all configuration in cmake.
270
271Internal Trusted Storage configurations
272---------------------------------------
273
274ITS service is enabled in top-level Profile Large CMake config file by default.
275
276The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by
277default. A platform/use case can overwrite the buffer size in its specific
278configuration extension according to its actual requirement of assets and Flash
279attributes.
280
281Profile Large CMake config file won't touch the configurations of device
282specific Flash hardware attributes.
283
284Protected Storage Secure Partition
285----------------------------------
286
287Data confidentiality, integrity and anti-rollback protection are enabled by
288default in PS.
289
290If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform
291hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can
292be executed in hardware crypto accelerator.
293
294If platforms don't integrate any off-chip storage device, platforms can disable
295PS in platform specific configuration extension file via
296``platform/ext<TFM_PLATFORM>/config.cmake``.
297
298BL2 setting
299-----------
300
301Profile Large enables MCUBoot provided by TF-M by default. A platform can
302overwrite this configuration by disabling MCUBoot in its configuration extension
303file ``platform/ext<TFM_PLATFORM>/config.cmake``.
304
305If MCUBoot provided by TF-M is enabled, multiple image boot is selected by
306default.
307
308If a device implements its own boot loader, the configurations are
309implementation defined.
310
311Software countermeasure against physical attacks
312------------------------------------------------
313
314Profile Large selects TF-M FIH library Profile Medium by specifying
315``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file.
316
317System integrators shall implement software countermeasures in platform specific
318implementations.
319
320Device configuration extension
321------------------------------
322
323To change default configurations and add platform specific configurations,
324a platform can add a platform configuration file at
325``platform/ext<TFM_PLATFORM>/config.cmake``
326
327Test configuration
328------------------
329
330Some cryptography tests are disabled due to the reduced MbedTLS config.
331Profile Large specific test configurations are also specified in Profile Large
332top-level CMake config file ``config/profile/profile_large_test.cmake``.
333
334.. table:: Profile Large crypto test configuration
335   :widths: auto
336   :align: center
337
338   +--------------------------------------------+---------------+-----------------------------------------+
339   | Configs                                    | Default value | Descriptions                            |
340   +============================================+===============+=========================================+
341   | ``TFM_CRYPTO_TEST_ALG_CBC``                | ``ON``        | Test CBC cryptography mode              |
342   +--------------------------------------------+---------------+-----------------------------------------+
343   | ``TFM_CRYPTO_TEST_ALG_CCM``                | ``ON``        | Test CCM cryptography mode              |
344   +--------------------------------------------+---------------+-----------------------------------------+
345   | ``TFM_CRYPTO_TEST_ALG_CFB``                | ``OFF``       | Test CFB cryptography mode              |
346   +--------------------------------------------+---------------+-----------------------------------------+
347   | ``TFM_CRYPTO_TEST_ALG_ECB``                | ``OFF``       | Test ECB cryptography mode              |
348   +--------------------------------------------+---------------+-----------------------------------------+
349   | ``TFM_CRYPTO_TEST_ALG_CTR``                | ``OFF``       | Test CTR cryptography mode              |
350   +--------------------------------------------+---------------+-----------------------------------------+
351   | ``TFM_CRYPTO_TEST_ALG_OFB``                | ``OFF``       | Test OFB cryptography mode              |
352   +--------------------------------------------+---------------+-----------------------------------------+
353   | ``TFM_CRYPTO_TEST_ALG_GCM``                | ``ON``        | Test GCM cryptography mode              |
354   +--------------------------------------------+---------------+-----------------------------------------+
355   | ``TFM_CRYPTO_TEST_ALG_SHA_384``            | ``OFF``       | Test SHA-384 cryptography algorithm     |
356   +--------------------------------------------+---------------+-----------------------------------------+
357   | ``TFM_CRYPTO_TEST_ALG_SHA_512``            | ``ON``        | Test SHA-512 cryptography algorithm     |
358   +--------------------------------------------+---------------+-----------------------------------------+
359   | ``TFM_CRYPTO_TEST_HKDF``                   | ``ON``        | Test HMAC-based key derivation function |
360   +--------------------------------------------+---------------+-----------------------------------------+
361   | ``TFM_CRYPTO_TEST_ECDH``                   | ``ON``        | Test ECDH key agreement algorithm       |
362   +--------------------------------------------+---------------+-----------------------------------------+
363   | ``TFM_CRYPTO_TEST_CHACHA20``               | ``OFF``       | Test ChaCha20 stream cipher             |
364   +--------------------------------------------+---------------+-----------------------------------------+
365   | ``TFM_CRYPTO_TEST_CHACHA20_POLY1305``      | ``OFF``       | Test ChaCha20-Poly1305 AEAD algorithm   |
366   +--------------------------------------------+---------------+-----------------------------------------+
367   | ``TFM_CRYPTO_TEST_SINGLE_PART_FUNCS``      | ``OFF``       | Test single-part operations in hash,    |
368   |                                            |               | MAC, AEAD and symmetric ciphers         |
369   +--------------------------------------------+---------------+-----------------------------------------+
370
371****************
372Platform support
373****************
374
375To enable Profile Large on a platform, the platform specific CMake file should
376be added into the platform support list in top-level Profile Large CMake config
377file.
378
379Building Profile Large
380======================
381
382To build Profile Large, argument ``TFM_PROFILE`` in build command line should be
383set to ``profile_large``.
384
385Take AN521 as an example:
386
387The following commands build Profile Large without test cases on **AN521** with
388build type **MinSizeRel**, built by **Armclang**.
389
390.. code-block:: bash
391
392   cd <TFM root dir>
393   mkdir build && cd build
394   cmake -DTFM_PLATFORM=arm/mps2/an521 \
395         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
396         -DTFM_PROFILE=profile_large \
397         -DCMAKE_BUILD_TYPE=MinSizeRel \
398         ../
399   cmake --build ./ -- install
400
401The following commands build Profile Large with regression test cases on
402**AN521** with build type **MinSizeRel**, built by **Armclang**.
403
404.. code-block:: bash
405
406   cd <TFM root dir>
407   mkdir build && cd build
408   cmake -DTFM_PLATFORM=arm/mps2/an521 \
409         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
410         -DTFM_PROFILE=profile_large \
411         -DCMAKE_BUILD_TYPE=MinSizeRel \
412         -DTEST_S=ON -DTEST_NS=ON \
413         ../
414   cmake --build ./ -- install
415
416More details of building instructions and parameters can be found TF-M build
417instruction guide [9]_.
418
419*********
420Reference
421*********
422
423.. [1] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>`
424
425.. [2] :doc:`Trusted Firmware-M Profile Medium Design </configuration/profiles/tfm_profile_medium>`
426
427.. [3] `PSA Certified Level 3 Lightweight Protection Profile <https://www.psacertified.org/app/uploads/2020/12/JSADEN009-PSA_Certified_Level_3_LW_PP-1.0-BET02.pdf>`_
428
429.. [4] `Arm Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/documentation/den0063/latest/>`_
430
431.. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 <https://tools.ietf.org/html/rfc5246>`_
432
433.. [6] :doc:`Physical attack mitigation in Trusted Firmware-M </design_docs/tfm_physical_attack_mitigation>`
434
435.. [7] :doc:`Crypto design </design_docs/services/tfm_crypto_design>`
436
437.. [8] :doc:`ITS integration guide </integration_guide/services/tfm_its_integration_guide>`
438
439.. [9] :doc:`TF-M build instruction </building/tfm_build_instruction>`
440
441--------------
442
443*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
444