aboutsummaryrefslogtreecommitdiff
path: root/docs/design_documents/profiles
diff options
context:
space:
mode:
Diffstat (limited to 'docs/design_documents/profiles')
-rw-r--r--docs/design_documents/profiles/index.rst12
-rw-r--r--docs/design_documents/profiles/tfm_profile_medium.rst477
-rw-r--r--docs/design_documents/profiles/tfm_profile_small.rst645
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.*