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