1######################################## 2Trusted Firmware-M Profile Medium Design 3######################################## 4 5************ 6Introduction 7************ 8 9Compared with Profile Small, Profile Medium aims to securely connect devices to 10Cloud services with asymmetric cipher support. 11Profile Medium target devices need more resources for more cipher algorithms 12and higher isolation levels. 13 14************** 15Overall design 16************** 17 18TF-M Profile Medium defines the following feature set: 19 20 - Firmware Framework 21 22 - Inter-Process Communication (IPC) model [PSA-FF-M]_ 23 - Isolation level 2 [PSA-FF-M]_ 24 25 - Internal Trusted Storage (ITS) 26 27 - Crypto 28 29 - Support both symmetric cryptography and asymmetric cryptography 30 - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for 31 IoT [RFC7925]_ and CoAP [RFC7252]_, including 32 33 - Authenticated Encryption with Associated Data (AEAD) algorithm 34 - Asymmetric key algorithm based signature and verification 35 - Public-key cryptography based key exchange 36 - Hash function 37 - HMAC for default Pseudorandom Function (PRF) 38 39 - Asymmetric digital signature and verification for Initial Attestation 40 Token (IAT) 41 42 - Initial Attestation 43 44 - Asymmetric key algorithm based Initial Attestation 45 46 - Lightweight boot 47 48 - Anti-rollback protection 49 - Multiple image boot 50 51 - Protected Storage (PS) if off-chip storage device is integrated 52 53 - Data confidentiality 54 - Data integrity 55 - Rollback protection 56 57************** 58Design details 59************** 60 61More details of TF-M Profile Medium design are described in following sections. 62 63Firmware framework 64================== 65 66Profile Medium with IPC model and isolation level 2 aims to support usage 67scenarios which require more complicated secure service model and additional 68protection to PSA RoT. 69 70Level 2 isolation 71----------------- 72 73Profile Medium selects isolation level 2 by default. In addition to isolation 74level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the 75Application Root of Trust (App RoT) in level 2 isolation. 76 77IPC model 78--------- 79 80Profile Medium enables IPC model by default. IPC model can achieve a more 81flexible framework and higher levels of isolation, but may require more memory 82footprint and bring in longer latency, compared to SFN model. 83 84TF-M IPC model implementation follows the PSA Firmware Framework for M 85(PSA-FF-M) [PSA-FF-M]_. 86 87Crypto service 88============== 89 90Compared to Profile Small, Profile Medium includes asymmetric cryptography to 91support direct connection to Cloud services via common protocols, such as 92TLS/DTLS 1.2. 93 94As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default 95selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires: 96 97 - ECDHE_ECDSA as key exchange algorithm. 98 - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm. 99 Platforms can implement AES-128-CCM with truncated authentication tag to 100 achieve less network bandwidth [RFC7925]_. 101 - SHA256 as Hash function. 102 - HMAC as Message Authentication Code algorithm. 103 104Applications can also support TLS PSK [RFC4279]_ cipher suites, such as 105``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_. 106 107.. note :: 108 109 **Implementation note** 110 111 Developers can replace default algorithms with others or implement more 112 algorithms according to actual usage scenarios and device capabilities. 113 114 If a Crypto hardware accelerator is integrated, the cipher suites and 115 algorithms also depend on those accelerator features. 116 117More details of cipher suite are described below. 118 119Digital signature and verification 120---------------------------------- 121 122ECDSA is selected by default in Profile Medium. 123ECDSA requires much shorter keys compared with RSA at the same security level. 124Therefore, ECDSA can cost less storage area for assets and less network 125bandwidth to setup a TLS connection. 126ECDSA is also preferred for forward compatibility of future TLS versions. 127 128As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More 129ECC curves can be added based on the requirements in production. 130 131If usage scenarios require RSA algorithm for backward compatibility and legacy 132applications, platforms can add RSA support or replace ECDSA with RSA. The 133cipher suite should be switched accordingly. 134 135AEAD algorithm 136-------------- 137 138If Protected Storage (PS) is implemented, it is recommended to select the same 139AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite. 140 141Internal Trusted Storage 142======================== 143 144The configuration of ITS is the same as those in Profile Small [PROFILE-S]_. 145 146Lightweight boot 147================ 148 149BL2 implementation can be device specific. Devices may implement diverse 150boot processes with different features and configurations. 151However, the boot loader must support anti-rollback protection. Boot loader must 152be able to prevent unauthorized rollback, to protect devices from being 153downgraded to earlier versions with known vulnerabilities. 154 155MCUBoot in TF-M is configured as multiple image boot by default in Profile 156Medium. In multiple image boot, secure and non-secure images can be signed 157independently with different keys and they can be updated separately. It can 158support multiple vendors scenarios, in which non-secure and secure images are 159generated and updated by different vendors. 160Multiple image boot may require more storage area compared with single image 161boot. 162 163Protected Storage 164================= 165 166PS service is required if an off-chip storage device is integrated and used on 167the platform. 168 169TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and 170integrity. It is recommended to select the same AEAD algorithm as the one used 171for TLS/DTLS cipher suite. 172 173Anti-rollback protection in PS relies on non-volatile counter(s) provided by 174TF-M Platform Secure Partition (SP). 175 176************** 177Implementation 178************** 179 180Overview 181======== 182 183The basic idea is to add dedicated profile CMake configuration files under 184folder ``config/profile`` for TF-M Profile Medium default configuration, the 185same as Profile Small does. 186 187The top-level Profile Medium config file collects all the necessary 188configuration flags and set them to default values, to explicitly enable the 189features required in Profile Medium and disable the unnecessary ones, during 190TF-M build. 191 192A platform/use case can provide a configuration extension file to overwrite 193Profile Medium default setting and append other configurations. 194This configuration extension file can be added via parameter 195``TFM_EXTRA_CONFIG_PATH`` in build command line. 196 197The behaviour of the Profile Medium build flow (particularly the order of 198configuration loading and overriding) can be found at 199:ref:`tfm_cmake_configuration` 200 201The details of configurations will be covered in each module in 202`Implementation details`_. 203 204Implementation details 205====================== 206 207This section discusses the details of Profile Medium implementation. 208 209Top-level configuration files 210----------------------------- 211 212The firmware framework configurations in ``config/profile/profile_medium`` are 213shown below. 214 215.. table:: Config flags in Profile Medium top-level CMake config file 216 :widths: auto 217 :align: center 218 219 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 220 | Configs | Default value | Descriptions | 221 +============================================+=====================================================================================================+=====================================+ 222 | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation | 223 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 224 | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | 225 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 226 | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | 227 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 228 | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | 229 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 230 | ``CRYPTO_ASYM_ENCRYPT_MODULE_ENABLED`` | ``OFF`` | Enable Crypto asymmetric | 231 | | | encryption operations | 232 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 233 | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path | 234 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 235 | ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_medium.h`` | Mbed Crypto PSA config file path | 236 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 237 | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | 238 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 239 | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service | 240 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 241 | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP | 242 +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ 243 244.. [1] PS service is enabled by default. Platforms without off-chip storage 245 devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS 246 service. See `Protected Storage Secure Partition`_ for details. 247 248.. Note:: 249 250 Where a configuration is the same as the default in 251 ``config/config_base.cmake``, it is omitted from the profile configuration 252 file. 253 254Test configuration 255^^^^^^^^^^^^^^^^^^ 256 257Standard regression test configuration applies. This means that enabling 258regression testing via 259 260``-DTEST_S=ON -DTEST_NS=ON`` 261 262Will enable testing for all enabled partitions. See above for details of enabled 263partitions. Because Profile Medium enables IPC model, the IPC tests are also 264enabled. 265 266Some cryptography tests are disabled due to the reduced Mbed Crypto config. 267 268.. table:: TFM options in Profile Medium top-level CMake config file 269 :widths: auto 270 :align: center 271 272 +--------------------------------------------+---------------+-----------------------------------------------+ 273 | Configs | Default value | Descriptions | 274 +============================================+===============+===============================================+ 275 | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | Disable CBC mode test | 276 +--------------------------------------------+---------------+-----------------------------------------------+ 277 | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Enable CCM mode test | 278 +--------------------------------------------+---------------+-----------------------------------------------+ 279 | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Disable CFB mode test | 280 +--------------------------------------------+---------------+-----------------------------------------------+ 281 | ``TFM_CRYPTO_TEST_ALG_ECB`` | ``OFF`` | Disable ECB mode test | 282 +--------------------------------------------+---------------+-----------------------------------------------+ 283 | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Disable CTR mode test | 284 +--------------------------------------------+---------------+-----------------------------------------------+ 285 | ``TFM_CRYPTO_TEST_ALG_OFB`` | ``OFF`` | Disable OFB mode test | 286 +--------------------------------------------+---------------+-----------------------------------------------+ 287 | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Disable GCM mode test | 288 +--------------------------------------------+---------------+-----------------------------------------------+ 289 | ``TFM_CRYPTO_TEST_ALG_SHA_384`` | ``OFF`` | Disable SHA-384 algorithm test | 290 +--------------------------------------------+---------------+-----------------------------------------------+ 291 | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Disable SHA-512 algorithm test | 292 +--------------------------------------------+---------------+-----------------------------------------------+ 293 | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Disable HKDF algorithm test | 294 +--------------------------------------------+---------------+-----------------------------------------------+ 295 | ``TFM_CRYPTO_TEST_ECDH`` | ``ON`` | Enable ECDH key agreement test | 296 +--------------------------------------------+---------------+-----------------------------------------------+ 297 | ``TFM_CRYPTO_TEST_CHACHA20`` | ``OFF`` | Disable ChaCha20 stream cipher test | 298 +--------------------------------------------+---------------+-----------------------------------------------+ 299 | ``TFM_CRYPTO_TEST_CHACHA20_POLY1305`` | ``OFF`` | Disable ChaCha20-Poly1305 AEAD algorithm test | 300 +--------------------------------------------+---------------+-----------------------------------------------+ 301 | ``TFM_CRYPTO_TEST_SINGLE_PART_FUNCS`` | ``OFF`` | Test single-part operations in hash, MAC, | 302 | | | AEAD and symmetric ciphers | 303 +--------------------------------------------+---------------+-----------------------------------------------+ 304 305Device configuration extension 306^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 307 308To change default configurations and add platform specific configurations, 309a platform can add a platform configuration file at 310``platform/ext<TFM_PLATFORM>/config.cmake`` 311 312Crypto service configurations 313----------------------------- 314 315Crypto Secure Partition 316^^^^^^^^^^^^^^^^^^^^^^^ 317 318TF-M Profile Medium enables Crypto SP in top-level CMake config file. 319The following PSA Crypto operationts are enabled by default. 320 321 - Hash operations 322 - Message authentication codes 323 - Symmetric ciphers 324 - AEAD operations 325 - Asymmetric key algorithm based signature and verification 326 - Key derivation 327 - Key management 328 329Mbed Crypto configurations 330^^^^^^^^^^^^^^^^^^^^^^^^^^ 331 332TF-M Profile Medium adds a dedicated Mbed Crypto config file 333``tfm_mbedcrypto_config_profile_medium.h`` and Mbed Crypto PSA config file 334``crypto_config_profile_medium.h`` at ``/lib/ext/mbedcrypto/mbedcrypto_config`` 335folder, instead of the common one ``tfm_mbedcrypto_config_default.h`` and 336``crypto_config_default.h`` [CRYPTO-DESIGN]_. 337 338Major Mbed Crypto configurations are set as listed below: 339 340 - Enable SHA256 341 - Enable generic message digest wrappers 342 - Enable AES 343 - Enable CCM mode for symmetric ciphers 344 - Disable other modes for symmetric ciphers 345 - Enable ECDH 346 - Enable ECDSA 347 - Select ECC curve ``secp256r1`` 348 - Other configurations required by selected option above 349 350Other configurations can be selected to optimize the memory footprint of Crypto 351module. 352 353A device/use case can append an extra config header to the Profile Medium 354default Mbed Crypto config file. This can be done by setting the 355``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform 356config file ``platform/ext<TFM_PLATFORM>/config.cmake``. This cmake variable is 357a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as 358it keeps all configuration in cmake. 359 360Internal Trusted Storage configurations 361--------------------------------------- 362 363ITS service is enabled in top-level Profile Medium CMake config file by default. 364 365The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to 36632 bytes by default. A platform/use case can overwrite the buffer size in its 367specific configuration extension according to its actual requirement of assets 368and Flash attributes. 369 370Profile Medium CMake config file won't touch the configurations of device 371specific Flash hardware attributes [ITS-INTEGRATE]_. 372 373Protected Storage Secure Partition 374---------------------------------- 375 376Data confidentiality, integrity and anti-rollback protection are enabled by 377default in PS. 378 379If PS is selected, AES-CCM is used as AEAD algorithm by default. It requires to 380enable PS implementation to select diverse AEAD algorithm. 381 382If platforms don't integrate any off-chip storage device, platforms can disable 383PS in platform specific configuration extension file via 384``platform/ext<TFM_PLATFORM>/config.cmake``. 385 386BL2 setting 387----------- 388 389Profile Medium enables MCUBoot provided by TF-M by default. A platform can 390overwrite this configuration by disabling MCUBoot in its configuration extension 391file ``platform/ext<TFM_PLATFORM>/config.cmake``. 392 393If MCUBoot provided by TF-M is enabled, multiple image boot is selected by 394default in TF-M Profile Medium top-level CMake config file. 395 396If a device implements its own boot loader, the configurations are 397implementation defined. 398 399**************** 400Platform support 401**************** 402 403To enable Profile Medium on a platform, the platform specific CMake file should 404be added into the platform support list in top-level Profile Medium CMake config 405file. 406 407Building Profile Medium 408======================= 409 410To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be 411set to ``profile_medium``. 412 413Take AN521 as an example: 414 415The following commands build Profile Medium without test cases on **AN521** with 416build type **MinSizeRel**, built by **Armclang**. 417 418.. code-block:: bash 419 420 cd <TFM root dir> 421 mkdir build && cd build 422 cmake -DTFM_PLATFORM=arm/mps2/an521 \ 423 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 424 -DTFM_PROFILE=profile_medium \ 425 -DCMAKE_BUILD_TYPE=MinSizeRel \ 426 ../ 427 cmake --build ./ -- install 428 429The following commands build Profile Medium with regression test cases on 430**AN521** with build type **MinSizeRel**, built by **Armclang**. 431 432.. code-block:: bash 433 434 cd <TFM root dir> 435 mkdir build && cd build 436 cmake -DTFM_PLATFORM=arm/mps2/an521 \ 437 -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ 438 -DTFM_PROFILE=profile_medium \ 439 -DCMAKE_BUILD_TYPE=MinSizeRel \ 440 -DTEST_S=ON -DTEST_NS=ON \ 441 ../ 442 cmake --build ./ -- install 443 444.. Note:: 445 446 - For devices with more contrained memory and flash requirements, it is 447 possible to build with either only TEST_S enabled or only TEST_NS enabled. 448 This will decrease the size of the test images. Note that both test suites 449 must still be run to ensure correct operation. 450 451More details of building instructions and parameters can be found TF-M build 452instruction guide [TFM-BUILD]_. 453 454********* 455Reference 456********* 457 458.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/documentation/den0063/latest/>`_ 459 460.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things <https://tools.ietf.org/html/rfc7925>`_ 461 462.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>` 463 464.. [RFC7252] `The Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7252>`_ 465 466.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) <https://tools.ietf.org/html/rfc4279>`_ 467 468.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS <https://tools.ietf.org/html/rfc7251>`_ 469 470.. [CRYPTO-DESIGN] :doc:`Crypto design </design_docs/services/tfm_crypto_design>` 471 472.. [ITS-INTEGRATE] :doc:`ITS integration guide </integration_guide/services/tfm_its_integration_guide>` 473 474.. [TFM-BUILD] :doc:`TF-M build instruction </building/tfm_build_instruction>` 475 476-------------- 477 478*Copyright (c) 2020-2022, Arm Limited. All rights reserved.* 479
