docs/configuration/profiles/tfm_profile_large.rst

#######################################
Trusted Firmware-M Profile Large Design
#######################################

************
Introduction
************

As one of TF-M Profiles, Profile Large protects less resource-constrained Arm
Cortex-M devices.

Compared to Profile Small [1]_ and Profile Medium [2]_, Profile Large aims to
enable more secure features to support higher level of security required in more
complex usage scenarios.

    - Isolation level 3 enables additional isolation between
      :term:`Application RoT` (App RoT) services.
    - More crypto algorithms and cipher suites are selected to securely connect
      devices to remote services offered by various major Cloud Service
      Providers (CSP)
    - Basic software countermeasures against physical attacks can be enabled.

Profile Large can be aligned as a reference implementation with the requirements
defined in PSA Certified Level 3 Lightweight Protection Profile [3]_.

**************
Overall design
**************

TF-M Profile Large defines the following feature set:

    - Firmware Framework

        - Inter-Process Communication (IPC) model [4]_
        - Isolation level 3 [4]_

    - Internal Trusted Storage (ITS)

    - Crypto

        - Support both symmetric ciphers and asymmetric ciphers
        - Asymmetric key based cipher suites defined in TLS 1.2 [5]_ to support
          direct secure connection to major CSPs, including

            - Authenticated Encryption with Associated Data (AEAD) algorithm
            - Asymmetric key algorithm based signature and verification
            - Public-key cryptography based key exchange
            - Hash function
            - HMAC for default Pseudorandom Function (PRF)

        - Asymmetric digital signature and verification for Initial Attestation
          Token (IAT)
        - Asymmetric algorithms for firmware image signature verification
        - Key derivation

    - Initial Attestation

        - Asymmetric key algorithm based Initial Attestation

    - Secure boot
        - Anti-rollback protection
        - Multiple image boot

    - Protected Storage (PS) if off-chip storage device is integrated

        - Data confidentiality
        - Data integrity
        - Rollback protection

    - Software countermeasures against physical attacks

**************
Design details
**************

More details of TF-M Profile Large design are described in following sections.

Firmware framework
==================

Profile Large selects IPC model and isolation level 3 by default.

Isolation level 3 supports additional isolation between App RoT services,
compared to isolation level 2. It can protect :term:`RoT` services from each
other when their vendors don't trust each other.

Crypto service
==============

Profile Large supports direct connection to Cloud services via common protocols,
such as TLS 1.2.

In some usage scenarios, PSA RoT can be managed by device manufacturer or other
vendors and is out of control of application developers.
Profile Large selects alternative crypto algorithms for each crypto function to
support multiple common cipher suites required by various major CSPs. Therefore,
application developers can support services for diverse CSPs on same devices
with Profile Large, without relying on PSA RoT upgrades of crypto.

Devices meeting Profile Large should be in a position to offer at least two
alternatives to every cryptographic primitive for symmetric, asymmetric and
hash, and be able to use them for encryption, AEAD, signature and verification.

It will cost more resource in Profile Large to support more crypto algorithms
and cipher suites, compared to Profile Medium [2]_.

Boot loader
===========

BL2 implementation can be device specific. Devices may implement diverse
boot processes with different features and configurations.
However, the boot loader must support anti-rollback protection. Boot loader must
be able to prevent unauthorized rollback, to protect devices from being
downgraded to earlier versions with known vulnerabilities.

MCUBoot in TF-M is configured as multiple image boot by default in Profile
Large. In multiple image boot, secure and non-secure images can be signed
independently with different keys and they can be updated separately. It can
support multiple vendors scenarios, in which non-secure and secure images are
generated and updated by different vendors.
Multiple image boot may cost larger memory footprint compared with single image
boot.

Boot loader can implement software countermeasures to mitigate physical attacks.

Protected Storage
=================

PS service is required if an off-chip storage device is integrated and used on
the platform.

Anti-rollback protection in PS relies on non-volatile counter(s) provided by
TF-M Platform :term:`Secure Partition` (SP).

Software countermeasures against physical attacks
=================================================

TF-M Profile Large enables TF-M Fault Injection Hardening (FIH) library Profile
Medium by default. It enables the following countermeasure techniques:

    - Control flow monitor
    - Failure loop hardening
    - Complex constants
    - Redundant variables and condition checks

Refer to TF-M physical attack mitigation design document [6]_ for FIH library
details.

.. note ::

    **TF-M FIH library is still under development**.

    TF-M FIH library hardens TF-M critical execution steps to make physical
    attacks more difficult, together with device hardware countermeasures.
    It is not guaranteed that TF-M FIH library is able to mitigate all kinds of
    physical attacks.

.. note ::

    **Implementation note**

    TF-M FIH library doesn't cover platform specific critical configurations.
    Platforms shall implement software countermeasures against physical attacks
    to protect platform specific implementation.

**************
Implementation
**************

Overview
========

The basic idea is to add dedicated profile CMake configuration files under
folder ``config/profile`` for TF-M Profile Large default configuration, the
same as other TF-M Profiles do.

The top-level Profile Large config file collects all the necessary configuration
flags and set them to default values, to explicitly enable the features required
in Profile Large and disable the unnecessary ones, during TF-M build.

A platform/use case can provide a configuration extension file to overwrite
Profile Large default setting and append other configurations.
This configuration extension file can be added via parameter
``TFM_EXTRA_CONFIG_PATH`` in build command line.

The behaviour of the Profile Large build flow (particularly the order of
configuration loading and overriding) can be found at
:ref:`tfm_cmake_configuration`

The details of configurations will be covered in each module in
`Implementation details`_.

Implementation details
======================

This section discusses the details of Profile Large implementation.

Top-level configuration files
-----------------------------

The firmware framework configurations in ``config/profile/profile_large`` are
shown below.

.. table:: Config flags in Profile Large top-level CMake config file
   :widths: auto
   :align: center

   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | Configs                                    | Descriptions                       | Default value                                                                                      |
   +============================================+====================================+====================================================================================================+
   | ``TFM_ISOLATION_LEVEL``                    | Select level 3 isolation           | ``3``                                                                                              |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | ``TFM_PARTITION_INTERNAL_TRUSTED_STORAGE`` | Enable ITS SP                      | ``ON``                                                                                             |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | ``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_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``  | MbedTLS PSA config file path       | ``${CMAKE_SOURCE_DIR}/lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_profile_large.h``         |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | ``TFM_PARTITION_INITIAL_ATTESTATION``      | Enable Initial Attestation service | ``ON``                                                                                             |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | ``TFM_PARTITION_PROTECTED_STORAGE`` [a]_   | Enable PS service                  | ``ON``                                                                                             |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+
   | ``TFM_PARTITION_PLATFORM``                 | Enable TF-M Platform SP            | ``ON``                                                                                             |
   +--------------------------------------------+------------------------------------+----------------------------------------------------------------------------------------------------+

.. [a] PS service is enabled by default. Platforms without off-chip storage
       devices can turn off ``TFM_PARTITION_PROTECTED_STORAGE`` to disable PS
       service. See `Protected Storage Secure Partition`_ for details.

Crypto service configurations
-----------------------------

Crypto Secure Partition
^^^^^^^^^^^^^^^^^^^^^^^

TF-M Profile Large enables Crypto SP in top-level CMake config file and selects
all the Crypto modules.

MbedTLS configurations
^^^^^^^^^^^^^^^^^^^^^^

TF-M Profile Large adds a dedicated MbedTLS config file
``tfm_mbedcrypto_config_profile_large.h`` and MbedTLS PSA config file
``crypto_config_profile_large.h`` under
``/lib/ext/mbedcrypto/mbedcrypto_config`` folder, instead of the common one
``tfm_mbedcrypto_config_default.h`` and ``crypto_config_default.h`` [7]_.

Major MbedTLS configurations are set as listed below:

    - Enable SHA256 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_test.cmake``.

.. table:: Profile Large crypto test configuration
   :widths: auto
   :align: center

   +--------------------------------------------+---------------+-----------------------------------------+
   | Configs                                    | Default value | Descriptions                            |
   +============================================+===============+=========================================+
   | ``TFM_CRYPTO_TEST_ALG_CBC``                | ``ON``        | Test CBC cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_CCM``                | ``ON``        | Test CCM cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_CFB``                | ``OFF``       | Test CFB cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_ECB``                | ``OFF``       | Test ECB cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_CTR``                | ``OFF``       | Test CTR cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_OFB``                | ``OFF``       | Test OFB cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_GCM``                | ``ON``        | Test GCM cryptography mode              |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_SHA_384``            | ``OFF``       | Test SHA-384 cryptography algorithm     |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ALG_SHA_512``            | ``ON``        | Test SHA-512 cryptography algorithm     |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_HKDF``                   | ``ON``        | Test HMAC-based key derivation function |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_ECDH``                   | ``ON``        | Test ECDH key agreement algorithm       |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_CHACHA20``               | ``OFF``       | Test ChaCha20 stream cipher             |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_CHACHA20_POLY1305``      | ``OFF``       | Test ChaCha20-Poly1305 AEAD algorithm   |
   +--------------------------------------------+---------------+-----------------------------------------+
   | ``TFM_CRYPTO_TEST_SINGLE_PART_FUNCS``      | ``OFF``       | Test single-part operations in hash,    |
   |                                            |               | MAC, AEAD and symmetric ciphers         |
   +--------------------------------------------+---------------+-----------------------------------------+

****************
Platform support
****************

To enable Profile Large on a platform, the platform specific CMake file should
be added into the platform support list in top-level Profile Large CMake config
file.

Building Profile Large
======================

To build Profile Large, argument ``TFM_PROFILE`` in build command line should be
set to ``profile_large``.

Take AN521 as an example:

The following commands build Profile Large without test cases on **AN521** with
build type **MinSizeRel**, built by **Armclang**.

.. code-block:: bash

   cd <TFM root dir>
   mkdir build && cd build
   cmake -DTFM_PLATFORM=arm/mps2/an521 \
         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
         -DTFM_PROFILE=profile_large \
         -DCMAKE_BUILD_TYPE=MinSizeRel \
         ../
   cmake --build ./ -- install

The following commands build Profile Large with regression test cases on
**AN521** with build type **MinSizeRel**, built by **Armclang**.

.. code-block:: bash

   cd <TFM root dir>
   mkdir build && cd build
   cmake -DTFM_PLATFORM=arm/mps2/an521 \
         -DTFM_TOOLCHAIN_FILE=../toolchain_ARMCLANG.cmake \
         -DTFM_PROFILE=profile_large \
         -DCMAKE_BUILD_TYPE=MinSizeRel \
         -DTEST_S=ON -DTEST_NS=ON \
         ../
   cmake --build ./ -- install

More details of building instructions and parameters can be found TF-M build
instruction guide [9]_.

*********
Reference
*********

.. [1] :doc:`Trusted Firmware-M Profile Small Design </configuration/profiles/tfm_profile_small>`

.. [2] :doc:`Trusted Firmware-M Profile Medium Design </configuration/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] :doc:`Physical attack mitigation in Trusted Firmware-M </technical_references/design_docs/tfm_physical_attack_mitigation>`

.. [7] :doc:`Crypto design </technical_references/design_docs/tfm_crypto_design>`

.. [8] :doc:`ITS integration guide </integration_guide/services/tfm_its_integration_guide>`

.. [9] :doc:`TF-M build instruction </building/tfm_build_instruction>`

--------------

*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*