diff options
Diffstat (limited to 'docs/design_documents/profiles')
-rw-r--r-- | docs/design_documents/profiles/index.rst | 12 | ||||
-rw-r--r-- | docs/design_documents/profiles/tfm_profile_medium.rst | 477 | ||||
-rw-r--r-- | docs/design_documents/profiles/tfm_profile_small.rst | 645 |
3 files changed, 0 insertions, 1134 deletions
diff --git a/docs/design_documents/profiles/index.rst b/docs/design_documents/profiles/index.rst deleted file mode 100644 index e856cf8078..0000000000 --- a/docs/design_documents/profiles/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -TF-M Profiles -============= - -.. toctree:: - :maxdepth: 1 - :glob: - - * - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/profiles/tfm_profile_medium.rst b/docs/design_documents/profiles/tfm_profile_medium.rst deleted file mode 100644 index 8413635cc9..0000000000 --- a/docs/design_documents/profiles/tfm_profile_medium.rst +++ /dev/null @@ -1,477 +0,0 @@ -######################################## -Trusted Firmware-M Profile Medium Design -######################################## - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -Compared with Profile Small, Profile Medium aims to securely connect devices to -Cloud services with asymmetric cipher support. -Profile Medium target devices need more resources for more cipher algorithms -and higher isolation levels. - -For more descriptions and background of TF-M Profile, please refer to Profile -Small design document [PROFILE-S]_. - -************** -Overall design -************** - -TF-M Profile Medium defines the following feature set: - - - Firmware Framework - - - Inter-Process Communication (IPC) model [PSA-FF-M]_ - - Isolation level 2 [PSA-FF-M]_ - - - Internal Trusted Storage (ITS) - - - Crypto - - - Support both symmetric ciphers and asymmetric ciphers - - Asymmetric key based cipher suite suggested in TLS/DTLS profiles for - IoT [RFC7925]_ and CoAP [RFC7252]_, 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) - - - Initial Attestation - - - Asymmetric key algorithm based Initial Attestation - - - Lightweight boot - - - Anti-rollback protection - - Multiple image boot - - - Protected Storage (PS) if off-chip storage device is integrated - - - Data confidentiality - - Data integrity - - Rollback protection - -************** -Design details -************** - -More details of TF-M Profile Medium design are described in following sections. - -Firmware framework -================== - -Profile Medium with IPC model and isolation level 2 aims to support usage -scenarios which require more complicated secure service model and additional -protection to PSA RoT. - -Level 2 isolation ------------------ - -Profile Medium selects isolation level 2 by default. In addition to isolation -level 1, the PSA Root of Trust (PSA RoT) is also protected from access by the -Application Root of Trust (App RoT) in level 2 isolation. - -IPC model ---------- - -Profile Medium enables IPC model by default. IPC model can achieve a more -flexible framework and higher levels of isolation, but may require more memory -footprint and bring in longer latency, compared to Library model. - -TF-M IPC model implementation follows the PSA Firmware Framework for M -(PSA-FF-M) [PSA-FF-M]_. - -Crypto service -============== - -Compared to Profile Small, Profile Medium includes asymmetric cipher to support -direct connection to Cloud services via common protocols, such as TLS/DTLS 1.2. - -As suggested in CoAP [RFC7252]_ and [RFC7925]_, TF-M Profile Medium by default -selects ``TLS_ECDHE_ECDSA_WITH_AES_128_CCM`` as reference, which requires: - - - ECDHE_ECDSA as key exchange algorithm. - - AES-128-CCM (AES CCM mode with 128-bit key) as AEAD algorithm. - Platforms can implement AES-128-CCM with truncated authentication tag to - achieve less network bandwidth [RFC7925]_. - - SHA256 as Hash function. - - HMAC as Message Authentication Code algorithm. - -Applications can also support TLS PSK [RFC4279]_ cipher suites, such as -``TLS_PSK_WITH_AES_128_CCM`` [RFC7925]_. - -.. note :: - - **Implementation note** - - Developers can replace default algorithms with others or implement more - algorithms according to actual usage scenarios and device capabilities. - - If a Crypto hardware accelerator is integrated, the cipher suites and - algorithms also depend on those accelerator features. - -More details of cipher suite are described below. - -Digital signature and verification ----------------------------------- - -ECDSA is selected by default in Profile Medium. -ECDSA requires much shorter keys compared with RSA at the same security level. -Therefore, ECDSA can cost less storage area for assets and less network -bandwidth to setup a TLS connection. -ECDSA is also preferred for forward compatibility of future TLS versions. - -As requested in [RFC7251]_, ECC curve ``secp256r1`` should be supported. More -ECC curves can be added based on the requirements in production. - -If usage scenarios require RSA algorithm for backward compatibility and legacy -applications, platforms can add RSA support or replace ECDSA with RSA. The -cipher suite should be switched accordingly. - -AEAD algorithm --------------- - -If Protected Storage (PS) is implemented, it is recommended to select the same -AEAD algorithm for PS service as the one used by TLS/DTLS cipher suite. - -Internal Trusted Storage -======================== - -The configuration of ITS is the same as those in Profile Small [PROFILE-S]_. - -Lightweight boot -================ - -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 -Medium. 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 require more storage area compared with single image -boot. - -Protected Storage -================= - -PS service is required if an off-chip storage device is integrated and used on -the platform. - -TF-M PS service relies on an AEAD algorithm to ensure data confidentiality and -integrity. It is recommended to select the same AEAD algorithm as the one used -for TLS/DTLS cipher suite. - -Anti-rollback protection in PS relies on non-volatile counter(s) provided by -TF-M Platform Secure Partition (SP). - -TF-M audit logging service -========================== - -TF-M audit logging service allows secure services in the system to log critical -system events and information. - -TF-M audit logging service is not enabled in Profile Medium since its IPC model -dedicated interface is not ready yet. - -.. note :: - - **Implementation note** - - Please note that there is no dedicated PSA specification for Audit Logging - yet. - The design, interfaces and implementation of TF-M audit logging service may - change. - -************** -Implementation -************** - -Overview -======== - -The basic idea is to add dedicated profile CMake configuration files under -folder ``config/profile`` for TF-M Profile Medium default configuration, the -same as Profile Small does. - -The top-level Profile Medium config file collects all the necessary -configuration flags and set them to default values, to explicitly enable the -features required in Profile Medium and disable the unnecessary ones, during -TF-M build. - -A platform/use case can provide a configuration extension file to overwrite -Profile Medium 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 Medium 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 Medium implementation. - -Top-level configuration files ------------------------------ - -The firmware framework configurations in ``config/profile/profile_medium`` are -shown below. - -.. table:: Config flags in Profile Medium top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_ISOLATION_LEVEL`` | ``2`` | Select level 2 isolation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PSA_API`` | ``True`` | Select IPC model | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_medium.h`` | Mbed Crypto config file path | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PROTECTED_STORAGE`` [1]_ | ``ON`` | Enable PS service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PLATFORM`` | ``ON`` | Enable TF-M Platform SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -.. [1] 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. - -.. Note:: - - Where a configuration is the same as the default in - ``config/config_default.cmake``, it is omitted from the profile configuration - file. - -Test configuration -^^^^^^^^^^^^^^^^^^ - -Standard regression test configuration applies. This means that enabling -regression testing via - -``-DTEST_S=ON -DTEST_NS=ON`` - -Will enable testing for all enabled partitions. See above for details of enabled -partitions. Because Profile Medium enables IPC mode, the IPC tests are also -enabled. - -Some cryptography tests are disabled due to the reduced Mbed Crypto config. - -.. table:: TFM options in Profile Medium top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | 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_CTR`` | ``OFF`` | Test CTR cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -Device configuration extension -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change default configurations and add platform specific configurations, -a platform can add a platform configuration file at -``platform/ext<TFM_PLATFORM>/config.cmake`` - -Crypto service configurations ------------------------------ - -Crypto Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Medium enables Crypto SP in top-level CMake config file and selects -all the Crypto modules. - -Mbed Crypto configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Medium adds a dedicated Mbed Crypto config file -``tfm_mbedcrypto_config_profile_medium.h`` at -``/lib/ext/mbedcrypto/mbedcrypto_config`` -file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [CRYPTO-DESIGN]_. - -Major Mbed Crypto configurations are set as listed below: - - - Enable SHA256 - - Enable generic message digest wrappers - - Enable AES - - Enable CCM mode for symmetric ciphers - - Disable other modes for symmetric ciphers - - Enable ECDH - - Enable ECDSA - - Select ECC curve ``secp256r1`` - - Other configurations required by selected option above - -Other configurations can be selected to optimize the memory footprint of Crypto -module. - -A device/use case can append an extra config header to the Profile Medium -default Mbed Crypto config file. This can be done by setting the -``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform -config file ``platform/ext<TFM_PLATFORM>/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 Medium CMake config file by default. - -The internal transient buffer size ``ITS_BUF_SIZE`` [ITS-INTEGRATE]_ is set to -32 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 Medium CMake config file won't touch the configurations of device -specific Flash hardware attributes [ITS-INTEGRATE]_. - -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. It requires to -enable PS implementation to select diverse AEAD algorithm. - -If platforms don't integrate any off-chip storage device, platforms can disable -PS in platform specific configuration extension file via -``platform/ext<TFM_PLATFORM>/config.cmake``. - -BL2 setting ------------ - -Profile Medium enables MCUBoot provided by TF-M by default. A platform can -overwrite this configuration by disabling MCUBoot in its configuration extension -file ``platform/ext<TFM_PLATFORM>/config.cmake``. - -If MCUBoot provided by TF-M is enabled, multiple image boot is selected by -default in TF-M Profile Medium top-level CMake config file. - -If a device implements its own boot loader, the configurations are -implementation defined. - -**************** -Platform support -**************** - -To enable Profile Medium on a platform, the platform specific CMake file should -be added into the platform support list in top-level Profile Medium CMake config -file. - -Building Profile Medium -======================= - -To build Profile Medium, argument ``TFM_PROFILE`` in build command line should be -set to ``profile_medium``. - -Take AN521 as an example: - -The following commands build Profile Medium without test cases on **AN521** with -build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd <TFM root dir> - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_medium \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - ../ - cmake --build ./ -- install - -The following commands build Profile Medium with regression test cases on -**AN521** with build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd <TFM root dir> - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_medium \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - -DTEST_S=ON -DTEST_NS=ON \ - ../ - cmake --build ./ -- install - -.. Note:: - - - For devices with more contrained memory and flash requirements, it is - possible to build with either only TEST_S enabled or only TEST_NS enabled. - This will decrease the size of the test images. Note that both test suites - must still be run to ensure correct operation. - -More details of building instructions and parameters can be found TF-M build -instruction guide [TFM-BUILD]_. - -********* -Reference -********* - -.. [PSA-FF-M] `Arm Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4>`_ - -.. [RFC7925] `Transport Layer Security (TLS) / Datagram Transport Layer Security (DTLS) Profiles for the Internet of Things <https://tools.ietf.org/html/rfc7925>`_ - -.. [PROFILE-S] :doc:`Trusted Firmware-M Profile Small Design </docs/design_documents/profiles/tfm_profile_small>` - -.. [RFC7252] `The Constrained Application Protocol (CoAP) <https://tools.ietf.org/html/rfc7252>`_ - -.. [RFC4279] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) <https://tools.ietf.org/html/rfc4279>`_ - -.. [RFC7251] `AES-CCM Elliptic Curve Cryptography (ECC) Cipher Suites for TLS <https://tools.ietf.org/html/rfc7251>`_ - -.. [CRYPTO-DESIGN] :doc:`Crypto design </docs/design_documents/tfm_crypto_design>` - -.. [ITS-INTEGRATE] :doc:`ITS integration guide </docs/reference/services/tfm_its_integration_guide>` - -.. [TFM-BUILD] :doc:`TF-M build instruction </docs/getting_started/tfm_build_instruction>` - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* diff --git a/docs/design_documents/profiles/tfm_profile_small.rst b/docs/design_documents/profiles/tfm_profile_small.rst deleted file mode 100644 index abd49c8c8f..0000000000 --- a/docs/design_documents/profiles/tfm_profile_small.rst +++ /dev/null @@ -1,645 +0,0 @@ -####################################### -Trusted Firmware-M Profile Small Design -####################################### - -:Authors: David Hu -:Organization: Arm Limited -:Contact: david.hu@arm.com - -************ -Introduction -************ - -The capabilities and resources may dramatically vary on different IoT devices. -Some IoT devices may have very limited memory resource. The program on those -devices should keep small memory footprint and basic functionalities. -On the other hand, some devices may consist of more memory and extended storage, -to support stronger software capabilities. - -Diverse IoT use cases also require different levels of security and requirements -on device resource. For example, use cases require different cipher -capabilities. Selecting cipher suites can be sensitive to memory footprint on -devices with constrained resource. - -Trusted Firmware-M (TF-M) defines 3 general profiles, Profile Small, -Profile Medium and Profile Large, to provide different levels of security to fit -diverse device capabilities and use cases. -Each profile specifies a predefined list of features, targeting typical use -cases with specific hardware constraints. Profiles can serve as reference -designs, based on which developers can continue further development and -configurations, according to use case. - -As one of the TF-M Profiles, TF-M Profile Small (Profile S) consists of -lightweight TF-M framework and basic Secure Services to keep smallest memory -footprint, supporting fundamental security features on devices with ultra -constrained resource. - -This profile enables connecting with Edge Gateways and IoT Cloud Services -supporting secure connection based solely on symmetric cryptography. - -This document summarizes and discusses the features specified in TF-M Profile -Small. - -************** -Overall design -************** - -TF-M Profile Small defines the following features: - - - Lightweight framework - - - Library model - - Level 1 isolation - - Buffer sharing allowed - - Single secure context - - - Crypto - - - Symmetric cipher only - - Cipher suite for symmetric-key algorithms based protocols, such as - cipher suites defined in TLS pre-shared key (TLS-PSK) [1]_. - - - Advanced Encryption Standard (AES) as symmetric crypto algorithm - - SHA256 as Hash function - - HMAC as Message Authentication Code algorithm - - - Internal Trusted Storage (ITS) - - - No encryption - - No rollback protection - - Decrease internal transient buffer size - - - Initial Attestation - - - Based on symmetric key algorithms - - - Lightweight boot - - - Single image boot - - Anti-rollback protection is enabled - - -Protected Storage, audit logging and other Secure Services provided by TF-M are -disabled by default. - -************** -Design details -************** - -More details of TF-M Profile Small design are discussed in following sections. - -Lightweight framework -===================== - -Library model -------------- - -Profile Small selects Library model in TF-M. Library model implements secure -function calls, via which clients directly call secure services. It provides a -more simple implementation of TF-M framework and may reduce memory footprint, -compared with Inter-Process Communication (IPC) model [2]_. - -.. note :: - - **Implementation note** - - Please note that there is no public dedicated specification for Library - model. - The design, interfaces and implementation of Library model in TF-M may - change. - -Level 1 isolation ------------------ - -So far, TF-M Library model only supports level 1 isolation [2]_, which isolates -Secure Processing Environment (SPE) from Non-secure Processing Environment -(NSPE). Neither level 2 nor level 3 isolation [2]_ is implemented in TF-M -Library model. - -PSA Root of Trust (PSA RoT) and Application Root of Trust (ARoT) are isolated -from each other in level 2 isolation. -Individual secure partitions are isolated from each other even within a -particular security domain (PSA RoT, ARoT), in level 3 isolation. - -Profile Small dedicated use cases with simple service model may not require -level 2 or level 3 isolation. Devices which Profile Small aims at may be unable -to implement stricter isolation, limited by hardware capabilities. - -Level 1 isolation reduces requirements enforced by hardware isolation and cost -of software for management. - -.. note :: - - **Security note** - - If a device or a use case enforces level 2 or level 3 isolation, it is - suggested to apply other configurations, other than TF-M Profile Small. - -Buffer sharing allowed ----------------------- - -To simplify interface and reduce memory footprint, TF-M Library model directly -handles client call input vectors from non-secure client buffers and later -writes results back to those buffers, without keeping a copy in a transient -buffer inside TF-M. - -.. note :: - - **Security note** - - There can be security vulnerabilities if non-secure client buffers are - directly shared between NSPE and SPE, such as Time-of-check to time-of-use - (TOCTOU) attack. - - Developers need to check if this can meet the Security Functional - Requirements (SFR) of the integration of their devices. - Some SFRs are listed in a set of example Threat Models and Security Analyses - (TMSA) offered by PSA for common IoT use cases. [3]_ - -Single secure context ---------------------- - -TF-M Library model only supports single secure context. - -It cannot support multiple contexts or the scheduling implemented in IPC model. -It neither can support multiple outstanding PSA client calls. - -But correspondingly, it can save memory footprint and runtime complexity in -context management and scheduling. - -.. note :: - - **Security note** - - Non-secure software should prevent triggering multiple outstanding PSA - client calls concurrently. Otherwise, it may crash current running secure - context. - -Crypto service -============== - -TF-M Profile Small only requires symmetric crypto since symmetric algorithms -require shorter keys and less computational burden, compared with asymmetric -crypto. - -By default, TF-M Profile Small requires the same capabilities as defined in -TLS-PSK, to support symmetric key algorithms based protocols. - -.. note :: - - **Implementation note** - - Please note that TF-M Profile Small doesn't require that TLS-PSK is - mandatory in applications. Instead, Profile Small only requires the same - capabilities as defined in TLS-PSK, such as one symmetric cipher algorithm - and one hash function. - -TF-M Profile Small selects TLS-PSK cipher suite TLS_PSK_WITH_AES_128_CCM [4]_ -as reference, which requires: - - - AES-128-CCM (AES CCM mode with 128-bit key) as symmetric crypto algorithm - - SHA256 as Hash function - - HMAC as Message Authentication Code algorithm - -TLS_PSK_WITH_AES_128_CCM is selected since it requires small key length and less -hardware capabilities, while keeping enough level of security. - -.. note :: - - **Implementation note** - - Developers can replace default algorithms with others or implement more - algorithms. - - Proper symmetric key algorithms and cipher suites should be selected - according to device capabilities, the use case and the requirement of peers - in connection. - - Refer to `Crypto service configuration`_ for implementation details of - configuring algorithms and cipher suites. - -.. note :: - - **Security note** - - It is recommended not to use MD5 or SHA-1 for message digests as they are - subject to collision attacks [5]_ [6]_. - -Secure Storage -============== - -TF-M Profile Small assumes that extremely constrained devices only contain basic -on-chip storage, without external or removable storage. -As a result, TF-M Profile Small includes ITS service and disables Protected -Storage service. - -Encryption and rollback protection ----------------------------------- - -Neither encryption nor rollback protection is enabled in current ITS -implementation. - -It is expected that ITS relies solely on the physical inaccessibility property -of on-chip storage, together with PSA isolation, without requiring additional -cryptographic protection. - -Internal transient buffer -------------------------- - -ITS implements a internal transient buffer [7]_ to hold the data read -from/written to storage, especially for flash, to solve the alignment and -security issues. - -The internal transient buffer is aligned to the flash device’s program unit. -Copying data to it from the caller can align all write requests to the flash -device’s program unit. -The internal transient buffer can help protect Flash access from some attacks, -such as TOCTOU attack. - -Although removing this internal buffer can save some memory consumption, -typically 512 bytes, it may bring alignment or security issues. -Therefore, to achieve a better trade-off between memory footprint and security, -TF-M Profile Small optimizes the internal buffer size to 32 bytes by default. - -As discussed in `Crypto service`_, TF-M Profile Small requires AES-128 and -SHA-256, which use 128-bit key and 256-bit key respectively. -Besides, either long public/private keys or PKI-based certificates should be -very rare as asymmetric crypto is not supported in Profile Small. -Therefore, a 32-byte internal buffer should cover the assets in TF-M Profile -Small use cases. - -The buffer size can be adjusted according to use case and device Flash -attributes. Refer to `Internal Trusted Storage configurations`_ for more -details. - -Initial Attestation -=================== - -Profile Small requires an Initial Attestation secure service based on symmetric -key algorithms. Refer to PSA Attestation API document [8]_ for details of -Initial Attestation based on symmetric key algorithms. - -It can heavily increase memory footprint to support Initial Attestation based on -asymmetric key algorithms, due to asymmetric ciphers and related PKI modules. - -.. note :: - - **Implementation note** - - As pointed out by PSA Attestation API document [8]_, the use cases of - Initial Attestation based on symmetric key algorithms can be limited due to - the associated infrastructure costs for key management and operational - complexities. It may also restrict the ability to interoperate with - scenarios that involve third parties. - - If asymmetric key algorithms based Initial Attestation is required in use - scenarios, it is recommended to select other TF-M Profiles which support - asymmetric key algorithms. - -.. note :: - - **Implementation note** - - It is recommended to utilize the same MAC algorithm supported in Crypto - service to complete the signing in ``COSE_Mac0``, to minimize memory - footprint. - -Lightweight boot -================ - -If MCUBoot provided by TF-M is enabled, single image boot [9]_ is selected by -default in Profile Small. -In case of single image boot, secure and non-secure images are handled as a -single blob and signed together during image generation. - -However, secure and non-secure images must be updated together in single image -boot. It may decrease the flexibility of image update and cost longer update -process. Since the image sizes should usually be small with limited -functionalities in Profile Small dedicated use case, the cost may still be -reasonable. - -BL2 implementation can be device specific. Devices may implement diverse -boot processes with different features and configurations. -However, anti-rollback protection is required as a mandatory feature of boot -loader. Boot loader should be able to prevent unauthorized rollback, to protect -devices from being downgraded to earlier versions with known vulnerabilities. - -************** -Implementation -************** - -Overview -======== - -The basic idea is to add dedicated profile CMake configuration files under -folder ``config/profile`` for TF-M Profile Small default configuration. - -The top-level Profile Small config file collects all the necessary -configuration flags and set them to default values, to explicitly enable the -features required in Profile Small and disable the unnecessary ones, during -TF-M build. - -A platform/use case can provide a configuration extension file to overwrite -Profile Small 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 Small 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 Small implementation. - -Top-level configuration files ------------------------------ - -The firmware framework configurations in ``config/profile/profile_small`` are -shown below. - -.. table:: TFM options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_ISOLATION_LEVEL`` | ``1`` | Select level 2 isolation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PSA_API`` | ``FALSE`` | Select IPC model | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | ``ON`` | Enable ITS SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``ITS_BUF_SIZE`` | ``32`` | ITS internal transient buffer size | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_CRYPTO`` | ``ON`` | Enable Crypto service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_MBEDCRYPTO_CONFIG_PATH`` | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_profile_small.h`` | Mbed Crypto config file path | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``CRYPTO_ASYMMETRIC_MODULE_DISABLED`` | ``ON`` | Disable asymmetric crypto | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_INITIAL_ATTESTATION`` | ``ON`` | Enable Initial Attestation service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``SYMMETRIC_INITIAL_ATTESTATION`` | ``ON`` | Enable symmetric attestation | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PROTECTED_STORAGE`` | ``OFF`` | Enable PS service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_PLATFORM`` | ``OFF`` | Enable TF-M Platform SP | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_PARTITION_AUDIT_LOG`` | ``OFF`` | Disable TF-M audit logging service | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -.. note :: - - **Implementation note** - - The following sections focus on the feature selection via configuration - setting. - Dedicated optimization on memory footprint is not covered in this document. - -Test configuration -^^^^^^^^^^^^^^^^^^ - -Standard regression test configuration applies. This means that enabling -regression testing via - -``-DTEST_S=ON -DTEST_NS=ON`` - -Will enable testing for all enabled partitions. See above for details of enabled -partitions. Because Profile Small does not enable IPC mode, the IPC tests are -not enabled. - -Some cryptography tests are disabled due to the reduced Mbed Crypto config. - -.. table:: TFM options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``TFM_CRYPTO_TEST_ALG_CBC`` | ``OFF`` | 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_CTR`` | ``OFF`` | Test CTR cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_GCM`` | ``OFF`` | Test GCM cryptography mode | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_ALG_SHA_512`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``TFM_CRYPTO_TEST_HKDF`` | ``OFF`` | Test SHA-512 cryptography algorithm | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -Device configuration extension -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To change default configurations and add platform specific configurations, -a platform can add a platform configuration file at -``platform/ext<TFM_PLATFORM>/config.cmake`` - -TF-M framework setting ----------------------- - -The top-level Profile Small CMake config file selects Library model and level 1 -isolation. - -Crypto service configuration ----------------------------- - -Crypto Secure Partition -^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Small enables Crypto Secure Partition (SP) in its top-level CMake -config file. Crypto SP modules not supported in TF-M Profile Small are disabled. -The disabled modules are shown below. - - - Disable asymmetric cipher - -Other modules and configurations [10]_ are kept as default values. - -Additional configuration flags with more fine granularity can be added to -control building of specific crypto algorithms and corresponding test cases. - -Mbed Crypto configurations -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -TF-M Profile Small adds a dedicated Mbed Crypto config file -``tfm_mbedcrypto_config_profile_small.h`` at -``/lib/ext/mbedcrypto/mbedcrypto_config`` -file, instead of the common one ``tfm_mbedcrypto_config_default.h`` [10]_. - -Major Mbed Crypto configurations are set as listed below: - - - Enable SHA256 - - Enable generic message digest wrappers - - Enable AES - - Enable CCM mode for symmetric ciphers - - Disable other modes for symmetric ciphers - - Disable asymmetric ciphers - - Disable HMAC-based key derivation function (HKDF) - -Other configurations can be selected to optimize the memory footprint of Crypto -module. - -A device/use case can append an extra config header to the Profile Small -default Mbed Crypto config file. This can be done by setting the -``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` cmake variable in the platform -config file ``platform/ext<TFM_PLATFORM>/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 Small CMake config file. - -The internal transient buffer size ``ITS_BUF_SIZE`` [7]_ is set to 32 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 Small CMake config file won't touch the configurations of device -specific Flash hardware attributes [7]_. - -Initial Attestation secure service ----------------------------------- - -TF-M Profile Small provides a reference implementation of symmetric key -algorithms based Initial Attestation, using HMAC SHA-256 as MAC algorithm in -``COSE_Mac0`` structure. The implementation follows PSA Attestation API document -[8]_. - -Profile Small top-level config file enables Initial Attestation secure service -and selects symmetric key algorithms based Initial Attestation by default. - - - Set ``TFM_PARTITION_INITIAL_ATTESTATION`` to ``ON`` - - Set ``SYMMETRIC_INITIAL_ATTESTATION`` to ``ON`` - -Symmetric and asymmetric key algorithms based Initial Attestation can share the -same generations of token claims, except Instance ID claim. - -Profile Small may implement the procedure or rely on a 3rd-party tool to -construct and sign ``COSE_Mac0`` structure. - -Details of symmetric key algorithms based Initial Attestation design will be -covered in a dedicated document. - -Disabled secure services ------------------------- - -Audit logging, Protected Storage, and Platform Service are disabled by default -in Profile Small top-level CMake config file. - -BL2 setting ------------ - -Profile Small enables MCUBoot provided by TF-M by default. A platform can -overwrite this configuration by disabling MCUBoot in its configuration extension -file ``platform/ext<TFM_PLATFORM>/config.cmake``. - -If MCUBoot provided by TF-M is enabled, single image boot is selected in TF-M -Profile Small top-level CMake config file. - -If a device implements its own boot loader, the configurations are -implementation defined. - -.. table:: BL2 options in Profile Small top-level CMake config file - :widths: auto - :align: center - - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | Configs | Default value | Descriptions | - +============================================+=====================================================================================================+=====================================+ - | ``BL2`` | ``ON`` | Enable MCUBoot bootloader | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - | ``MCUBOOT_IMAGE_NUMBER`` | ``1`` | Combine S and NS images | - +--------------------------------------------+-----------------------------------------------------------------------------------------------------+-------------------------------------+ - -**************** -Platform support -**************** - -Building Profile Small -====================== - -To build Profile Small, argument ``TFM_PROFILE`` in build command line should be -set to ``profile_small``. - -Take AN521 as an example. - -The following commands build Profile Small without test cases on **AN521** with -build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd <TFM root dir> - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_small \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - ../ - cmake --build ./ -- install - -The following commands build Profile Small with regression test cases on **AN521** -with build type **MinSizeRel**, built by **Armclang**. - -.. code-block:: bash - - cd <TFM root dir> - mkdir build && cd build - cmake -DTFM_PLATFORM=mps2/an521 \ - -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \ - -DTFM_PROFILE=profile_small \ - -DCMAKE_BUILD_TYPE=MinSizeRel \ - -DTEST_S=ON -DTEST_NS=ON \ - ../ - cmake --build ./ -- install - -.. Note:: - - - For devices with more contrained memory and flash requirements, it is - possible to build with either only TEST_S enabled or only TEST_NS enabled. - This will decrease the size of the test images. Note that both test suites - must still be run to ensure correct operation. - -More details of building instructions and parameters can be found TF-M build -instruction guide [11]_. - -********* -Reference -********* - -.. [1] `Pre-Shared Key Ciphersuites for Transport Layer Security (TLS) <https://tools.ietf.org/html/rfc4279>`_ - -.. [2] `DEN0063 Arm Platform Security Architecture Firmware Framework 1.0 <https://developer.arm.com/-/media/Files/pdf/DeviceSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4>`_ - -.. [3] `PSA analyze stage <https://developer.arm.com/architectures/security-architectures/platform-security-architecture#analyze>`_ - -.. [4] `AES-CCM Cipher Suites for Transport Layer Security (TLS) <https://tools.ietf.org/html/rfc6655>`_ - -.. [5] `Updated Security Considerations for the MD5 Message-Digest and the HMAC-MD5 Algorithms <https://tools.ietf.org/html/rfc6151>`_ - -.. [6] `Transitioning the Use of Cryptographic Algorithms and Key Lengths <https://www.nist.gov/publications/transitioning-use-cryptographic-algorithms-and-key-lengths>`_ - -.. [7] :doc:`ITS integration guide </docs/reference/services/tfm_its_integration_guide>` - -.. [8] `PSA Attestation API 1.0 (ARM IHI 0085) <https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Implement/IHI0085-PSA_Attestation_API-1.0.2.pdf?revision=eef78753-c77e-4b24-bcf0-65596213b4c1&la=en&hash=E5E0353D612077AFDCE3F2F3708A50C77A74B2A3>`_ - -.. [9] :doc:`Secure boot </docs/getting_started/tfm_secure_boot>` - -.. [10] :doc:`Crypto design </docs/design_documents/tfm_crypto_design>` - -.. [11] :doc:`TF-M build instruction </docs/getting_started/tfm_build_instruction>` - --------------- - -*Copyright (c) 2020, Arm Limited. All rights reserved.* |