####################################### Trusted Firmware-M Profile Large Design ####################################### ************ Introduction ************ As one of TF-M Profiles, Profile Large protects less resource-constrained Arm Cortex-M devices. Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to enable more secure features to support higher level of security required in more complex usage scenarios. - Isolation level 3 enables additional isolation between :term:`Application RoT` (App RoT) services. - More crypto algorithms and cipher suites are selected to securely connect devices to remote services offered by various major Cloud Service Providers (CSP) - Basic software countermeasures against physical attacks can be enabled. Profile Large can be aligned as a reference implementation with the requirements defined in PSA Certified Level 3 Lightweight Protection Profile [3]_. ************** Overall design ************** TF-M Profile Large defines the following feature set: - Firmware Framework - Inter-Process Communication (IPC) model [4]_ - Isolation level 3 [4]_ - Internal Trusted Storage (ITS) - Crypto - Support both symmetric ciphers and asymmetric ciphers - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support direct secure connection to major CSPs, including - Authenticated Encryption with Associated Data (AEAD) algorithm - Asymmetric key algorithm based signature and verification - Public-key cryptography based key exchange - Hash function - HMAC for default Pseudorandom Function (PRF) - Asymmetric digital signature and verification for Initial Attestation Token (IAT) - Asymmetric algorithms for firmware image signature verification - Key derivation - Initial Attestation - Asymmetric key algorithm based Initial Attestation - Secure boot - Anti-rollback protection - Multiple image boot - Protected Storage (PS) if off-chip storage device is integrated - Data confidentiality - Data integrity - Rollback protection - Software countermeasures against physical attacks ************** Design details ************** More details of TF-M Profile Large design are described in following sections. Firmware framework ================== Profile Large selects IPC model and isolation level 3 by default. Isolation level 3 supports additional isolation between App RoT services, compared to isolation level 2. It can protect :term:`RoT` services from each other when their vendors don't trust each other. Crypto service ============== Profile Large supports direct connection to Cloud services via common protocols, such as TLS 1.2. In some usage scenarios, PSA RoT can be managed by device manufacturer or other vendors and is out of control of application developers. Profile Large selects alternative crypto algorithms for each crypto function to support multiple common cipher suites required by various major CSPs. Therefore, application developers can support services for diverse CSPs on same devices with Profile Large, without relying on PSA RoT upgrades of crypto. Devices meeting Profile Large should be in a position to offer at least two alternatives to every cryptographic primitive for symmetric, asymmetric and hash, and be able to use them for encryption, AEAD, signature and verification. It will cost more resource in Profile Large to support more crypto algorithms and cipher suites, compared to Profile Medium [2]_. Boot loader =========== BL2 implementation can be device specific. Devices may implement diverse boot processes with different features and configurations. However, the boot loader must support anti-rollback protection. Boot loader must be able to prevent unauthorized rollback, to protect devices from being downgraded to earlier versions with known vulnerabilities. MCUBoot in TF-M is configured as multiple image boot by default in Profile Large. In multiple image boot, secure and non-secure images can be signed independently with different keys and they can be updated separately. It can support multiple vendors scenarios, in which non-secure and secure images are generated and updated by different vendors. Multiple image boot may cost larger memory footprint compared with single image boot. Boot loader can implement software countermeasures to mitigate physical attacks. Protected Storage ================= PS service is required if an off-chip storage device is integrated and used on the platform. Anti-rollback protection in PS relies on non-volatile counter(s) provided by TF-M Platform :term:`Secure Partition` (SP). Software countermeasures against physical attacks ================================================= TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile Medium by default. It enables the following countermeasure techniques: - Control flow monitor - Failure loop hardening - Complex constants - Redundant variables and condition checks Refer to TF-M physical attack mitigation design document [6]_ for FIH library details. .. note :: **TF-M FIH library is still under development**. TF-M FIH library hardens TF-M critical execution steps to make physical attacks more difficult, together with device hardware countermeasures. It is not guaranteed that TF-M FIH library is able to mitigate all kinds of physical attacks. .. note :: **Implementation note** TF-M FIH library doesn't cover platform specific critical configurations. Platforms shall implement software countermeasures against physical attacks to protect platform specific implementation. ************** Implementation ************** Overview ======== The basic idea is to add dedicated profile CMake configuration files under folder ``config/profile`` for TF-M Profile Large default configuration, the same as other TF-M Profiles do. The top-level Profile Large config file collects all the necessary configuration flags and set them to default values, to explicitly enable the features required in Profile Large and disable the unnecessary ones, during TF-M build. A platform/use case can provide a configuration extension file to overwrite Profile Large default setting and append other configurations. This configuration extension file can be added via parameter ``TFM_EXTRA_CONFIG_PATH`` in build command line. The behaviour of the Profile Large build flow (particularly the order of configuration loading and overriding) can be found at :ref:`tfm_cmake_configuration` The details of configurations will be covered in each module in `Implementation details`_. Implementation details ====================== This section discusses the details of Profile Large implementation. Top-level configuration files ----------------------------- The firmware framework configurations in ``config/profile/profile_large`` are shown below. .. table:: Config flags in Profile Large top-level CMake config file :widths: auto :align: center +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | Configs | Descriptions | Default value | +============================================+====================================+====================================================================================================+ | ``TFM_ISOLATION_LEVEL`` | Select level 3 isolation | ``3`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP | ``ON`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_PARTITION_CRYPTO`` | Enable Crypto service | ``ON`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | MbedTLS config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_large.h`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH`` | MbedTLS PSA config file path | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_large.h`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_PARTITION_INITIAL_ATTESTATION`` | Enable Initial Attestation service | ``ON`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_ | Enable PS service | ``ON`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ | ``TFM_PARTITION_PLATFORM`` | Enable TF-M Platform SP | ``ON`` | +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+ .. [a] PS service is enabled by default. Platforms without off-chip storage devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS service. See `Protected Storage Secure Partition`_ for details. Crypto service configurations ----------------------------- Crypto Secure Partition ^^^^^^^^^^^^^^^^^^^^^^^ TF-M Profile Large enables Crypto SP in top-level CMake config file and selects all the Crypto modules. MbedTLS configurations ^^^^^^^^^^^^^^^^^^^^^^ TF-M Profile Large adds a dedicated MbedTLS config file ``tfm_mbedcrypto_config_profile_large.h`` and MbedTLS PSA config file ``crypto_config_profile_large.h`` under ``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one ``tfm_mbedcrypto_config_default.h`` and ``crypto_config_default.h`` [7]_. Major MbedTLS configurations are set as listed below: - Enable SHA256, SHA384 and SHA512 - Enable generic message digest wrappers - Enable AES - Enable CCM mode, GCM mode, CTR mode, CFB mode and CBC mode for symmetric ciphers - Disable other modes for symmetric ciphers - Enable ECDH - Enable ECDSA - Enable RSA - Select ECC curve ``secp256r1`` and ``secp384r1`` - Enable HMAC-based key derivation function - Other configurations required by selected option above A device/use case can append an extra config header to the Profile Large default MbedTLS config file to override the default settings. This can be done by setting the ``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform config file ``platform/ext/config.cmake``. This cmake variable is a wrapper around the ``MBEDTLS_USER_CONFIG_FILE`` options, but is preferred as it keeps all configuration in cmake. Internal Trusted Storage configurations --------------------------------------- ITS service is enabled in top-level Profile Large CMake config file by default. The internal transient buffer size ``ITS_BUF_SIZE`` [8]_ is set to 64 bytes by default. A platform/use case can overwrite the buffer size in its specific configuration extension according to its actual requirement of assets and Flash attributes. Profile Large CMake config file won't touch the configurations of device specific Flash hardware attributes. Protected Storage Secure Partition ---------------------------------- Data confidentiality, integrity and anti-rollback protection are enabled by default in PS. If PS is selected, AES-CCM is used as AEAD algorithm by default. If platform hardware crypto accelerator supports the AEAD algorithm, the AEAD operations can be executed in hardware crypto accelerator. If platforms don't integrate any off-chip storage device, platforms can disable PS in platform specific configuration extension file via ``platform/ext/config.cmake``. BL2 setting ----------- Profile Large enables MCUBoot provided by TF-M by default. A platform can overwrite this configuration by disabling MCUBoot in its configuration extension file ``platform/ext/config.cmake``. If MCUBoot provided by TF-M is enabled, multiple image boot is selected by default. If a device implements its own boot loader, the configurations are implementation defined. Software countermeasure against physical attacks ------------------------------------------------ Profile Large selects TF-M FIH library Profile Medium by specifying ``-DTFM_FIH_PROFILE=MEDIUM`` in top-level CMake config file. System integrators shall implement software countermeasures in platform specific implementations. Device configuration extension ------------------------------ To change default configurations and add platform specific configurations, a platform can add a platform configuration file at ``platform/ext/config.cmake`` Test configuration ------------------ Some cryptography tests are disabled due to the reduced MbedTLS config. Profile Large specific test configurations are also specified in Profile Large top-level CMake config file ``config/profile/profile_large_test.cmake``. .. table:: Profile Large crypto test configuration :widths: auto :align: center +--------------------------------------------+---------------+-----------------------------------------+ | Configs | Default value | Descriptions | +============================================+===============+=========================================+ | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``ON`` | Test CBC cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_CCM`` | ``ON`` | Test CCM cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_CFB`` | ``OFF`` | Test CFB cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_ECB`` | ``OFF`` | Test ECB cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_CTR`` | ``OFF`` | Test CTR cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_OFB`` | ``OFF`` | Test OFB cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``ON`` | Test GCM cryptography mode | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_SHA_384`` | ``OFF`` | Test SHA-384 cryptography algorithm | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``ON`` | Test SHA-512 cryptography algorithm | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_HKDF`` | ``ON`` | Test HMAC-based key derivation function | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_ECDH`` | ``ON`` | Test ECDH key agreement algorithm | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_CHACHA20`` | ``OFF`` | Test ChaCha20 stream cipher | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_CHACHA20_POLY1305`` | ``OFF`` | Test ChaCha20-Poly1305 AEAD algorithm | +--------------------------------------------+---------------+-----------------------------------------+ | ``TFM_CRYPTO_TEST_SINGLE_PART_FUNCS`` | ``OFF`` | Test single-part operations in hash, | | | | MAC, AEAD and symmetric ciphers | +--------------------------------------------+---------------+-----------------------------------------+ **************** Platform support **************** To enable Profile Large on a platform, the platform specific CMake file should be added into the platform support list in top-level Profile Large CMake config file. Building Profile Large ====================== To build Profile Large, argument ``TFM_PROFILE`` in build command line should be set to ``profile_large``. Take AN521 as an example: The following commands build Profile Large without test cases on **AN521** with build type **MinSizeRel**, built by **Armclang**. .. code-block:: bash cd mkdir build && cd build cmake -DTFM_PLATFORM=arm/mps2/an521 \ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ -DTFM_PROFILE=profile_large \ -DCMAKE_BUILD_TYPE=MinSizeRel \ ../ cmake --build ./ -- install The following commands build Profile Large with regression test cases on **AN521** with build type **MinSizeRel**, built by **Armclang**. .. code-block:: bash cd mkdir build && cd build cmake -DTFM_PLATFORM=arm/mps2/an521 \ -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ -DTFM_PROFILE=profile_large \ -DCMAKE_BUILD_TYPE=MinSizeRel \ -DTEST_S=ON -DTEST_NS=ON \ ../ cmake --build ./ -- install More details of building instructions and parameters can be found TF-M build instruction guide [9]_. ********* Reference ********* .. [1] :doc:`Trusted Firmware-M Profile Small Design ` .. [2] :doc:`Trusted Firmware-M Profile Medium Design ` .. [3] `PSA Certified Level 3 Lightweight Protection Profile `_ .. [4] `Arm Platform Security Architecture Firmware Framework 1.0 `_ .. [5] `The Transport Layer Security (TLS) Protocol Version 1.2 `_ .. [6] :doc:`Physical attack mitigation in Trusted Firmware-M ` .. [7] :doc:`Crypto design ` .. [8] :doc:`ITS integration guide ` .. [9] :doc:`TF-M build instruction ` -------------- *Copyright (c) 2021-2022, Arm Limited. All rights reserved.*