1TF-M Crypto Service design 2========================== 3 4:Author: Antonio de Angelis 5:Organization: Arm Limited 6:Contact: Antonio de Angelis <antonio.deangelis@arm.com> 7 8.. contents:: Table of Contents 9 10Abstract 11-------- 12 13This document describes the design of the TF-M Cryptographic Secure Service 14(in short, TF-M Crypto service). 15 16Introduction 17------------ 18 19The TF-M Crypto service provides an implementation of the PSA Certified Crypto 20APIs in a PSA RoT secure partition in TF-M. It is based on the Mbed TLS 21project, which provides a reference implementation of the PSA Crypto APIs as a 22`C` software library. For more details on the PSA Crypto APIs refer to [1]_, 23while for the Mbed TLS reference software refer to [2]_ and [3]_ 24 25The service can be requested by other services running in the SPE, or by 26applications running in the NSPE, and its aim is to provide cryptographic 27primitives in a secure and efficient way, either via software or by routing the 28calls to any underlying crypto hardware accelerator or secure element that the 29platform might provide. 30 31Components 32---------- 33 34The TF-M Crypto service is implemented by a number of different firmware 35components residing in the Crypto partition, which are listed below: 36 37.. table:: Components table 38 :widths: auto 39 40 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 41 | **Component name** | **Description** | **Location** | 42 +=============================+===============================================================+======================================================================+ 43 | Client API interface | This module exports the PSA Crypto API to be callable from the| ``interface/src/tfm_crypto_api.c`` | 44 | | users, which are called also `clients`. They could be either | | 45 | | other secure partitions or Non Secure world based callers. | | 46 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 47 | Mbed TLS ``libmbedcrypto.a``| The Mbed TLS ``libmbedcrypto.a`` library is used in the | Needed as dependency specified by the ``MBEDCRYPTO_PATH`` CMake | 48 | | service as a cryptographic `backend` library which provides | configuration option | 49 | | the APIs to implement a PSA Crypto `core`, SW based crypto | | 50 | | primitives and wrappers for HW crypto accelerators and Secure | | 51 | | Elements. It exposes those through the PSA Crypto APIs | | 52 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 53 | Init module | This module handles the initialisation of the service objects | ``secure_fw/partitions/crypto/crypto_init.c`` | 54 | | during TF-M boot and provides the infrastructure to service | | 55 | | requests when TF-M is built for IPC or SFN model. | | 56 | | The dispatching mechanism of IPC requests is based on a look | | 57 | | up table of function pointers. | | 58 | | This design allows for better scalability and support of a | | 59 | | higher number of Secure functions with minimal overhead and | | 60 | | duplication of code. | | 61 | | This module is in charge of providing an ID of the caller of | | 62 | | each API in the backend, allowing to enforce key ownership | | 63 | | policies. | | 64 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 65 | Alloc module | This module handles the allocation of contexts for multipart | ``secure_fw/partitions/crypto/crypto_alloc.c`` | 66 | | operations in the Secure world. This is required because the | | 67 | | caller view of contexts, i.e. `clients`, does not contain any | | 68 | | sensible information but just a number handle which is then | | 69 | | used by the service itself to match the context to the actual | | 70 | | context information which will be stored securely in the TF-M | | 71 | | crypto partition private memory. This is enabled by setting | | 72 | | ``MBEDTLS_PSA_CRYPTO_CLIENT`` option on the caller side. Note | | 73 | | that setting this option on the client side is a hard | | 74 | | requirement in order for the clients to work correctly | | 75 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 76 | Service modules | These modules (AEAD, Asymmetric, Cipher, Hash, Key Derivation,| ``secure_fw/partitions/crypto/crypto_aead.c`` | 77 | | Key Management, MAC, Random Number Generation) represent a | ``secure_fw/partitions/crypto/crypto_asymmetric.c`` | 78 | | thin layer which is in charge of servicing the calls from the | ``secure_fw/partitions/crypto/crypto_cipher.c`` | 79 | | clients. They provide parameter sanitization and context | ``secure_fw/partitions/crypto/crypto_hash.c`` | 80 | | retrieval for multipart operations, and dispatching to the | ``secure_fw/partitions/crypto/crypto_key_derivation.c`` | 81 | | corresponding backend library function exposed by the | ``secure_fw/partitions/crypto/crypto_key_management.c`` | 82 | | underlying library. | ``secure_fw/partitions/crypto/crypto_mac.c`` | 83 | | | ``secure_fw/partitions/crypto/crypto_rng.c`` | 84 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 85 | Backend library abstraction | This module contains several APIs to abstract the interface | ``secure_fw/partitions/crypto/crypto_library.*`` | 86 | | towards the backend library, which must provide the PSA Crypto| | 87 | | core layer, key management, SW based crypto and possibly | | 88 | | interfaces for HW crypto accelerators and Secure Elements | | 89 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 90 | Manifest | The manifest file is a description of the service components. | ``secure_fw/partitions/crypto/tfm_crypto.yaml`` | 91 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 92 | CMake, Kconfig and headers | The CMake files are used by the TF-M CMake build system to | ``secure_fw/partitions/crypto/CMakeLists.txt`` | 93 | | build the service as part of the Secure FW build. The service | ``secure_fw/partitions/crypto/Kconfig`` | 94 | | is built as a static library | ``secure_fw/partitions/crypto/Kconfig.comp`` | 95 | | (``libtfm_psa_rot_partition_crypto.a``). | ``secure_fw/partitions/crypto/config_crypto_check.h`` | 96 | | The service itself depends on the build of the underlying | ``secure_fw/partitions/crypto/config_engine_buf.h`` | 97 | | backend library, by default the ``libmbedcrypto.a`` target, a | ``secure_fw/partitions/crypto/tfm_crypto_api.h`` | 98 | | static library built by the Mbed TLS build system. | ``secure_fw/partitions/crypto/crypto_spe.h`` | 99 | | The ``tfm_crypto_api.h`` header contains public service APIs, | ``interface/include/tfm_crypto_defs.h`` | 100 | | which expose each module's interface. The header available in | | 101 | | the interface, ``tfm_crypto_defs.h``, contains types and | | 102 | | definitions to build the client interface of the service, i.e.| | 103 | | towards other services or NS world. | | 104 | | Finally, the ``crypto_spe.h`` header is used during the | | 105 | | build of the Mbed TLS library, when the configuration option | | 106 | | ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a custom prefix | | 107 | | to the PSA API symbols so that duplication of symbol names is | | 108 | | avoided. The prefix used for the symbols of the library is | | 109 | | chosen to be ``mbedcrypto__``. | | 110 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 111 | TF-M Crypto key abstraction | The TF-M Crypto service has its own type definition to be able| ``secure_fw/partitions/crypto/tfm_crypto_key.h`` | 112 | | to identify a key ID with its own owner. The definition of an | | 113 | | owner is provided by the TF-M Firmware Framework and is out of| | 114 | | the scope of the service itself and the PSA Crypto APIs spec. | | 115 | | The underlying library in practice must provide the same | | 116 | | functionality, i.e handle key IDs with associated owner info. | | 117 | | For Mbed TLS, this is accomplished by the type | | 118 | | ``mbedtls_svc_key_id_t`` when the config option of Mbed TLS | | 119 | | ``MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER`` is defined. Note | | 120 | | that setting this option in Mbed TLS is a hard requirement for| | 121 | | when the library is built on the service side, while it shall | | 122 | | never be set when the headers are included for client side | | 123 | | components (i.e. other partitions or NS interface). | | 124 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 125 | Documentation | The | ``docs/integration_guide/services/tfm_crypto_integration_guide.rst`` | 126 | | :ref:`integration guide <tfm-crypto-integration-guide-label>` | | 127 | | contains the description of the TF-M Crypto service modules | | 128 | | and interfaces. | | 129 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 130 131The interaction between the different components is described by the 132block diagram in :numref:`block_diagram-label` 133 134.. _block_diagram-label: 135.. figure:: /design_docs/media/psa_rot_crypto_service_architecture.png 136 137 Block diagram of the firmware architecture of the TF-M Crypto service. Dotted 138 lines between services represent isolation boundaries once runtime firmware 139 is initialized, i.e. TF-M init phase has completed. The diagram is simplified 140 and shows only the major functional blocks, for a more detailed 141 ``libmbedcrypto.a`` architecture please refer to [3]_. 142 143Relationship between Mbed TLS and the TF-M Crypto service 144--------------------------------------------------------- 145 146TF-M Crypto as a particular configuration of Mbed TLS 147~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 148 149Up until `TF-Mv2.0`, the TF-M Crypto service used to provide its own separate 150implementation of the PSA Certified Crypto APIs, i.e. it provided its own 151version of the implementation defined aspects of the specifications. Starting 152from `TF-Mv2.1`, the TF-M Crypto service fully aligns to the implementation 153defined by the Mbed TLS project, i.e. its implementation defined aspects are 154the same as the ones defined by Mbed TLS. 155 156As a consequence, starting from `TF-Mv2.1` the PSA Crypto headers available 157in TF-M are a copy of those distributed by the Mbed TLS project. TF-M just 158uses them and won't accept any contribution to them, as those need to be 159discussed in the scope of the Mbed TLS project. 160 161TF-M then represents just a configuration of the Mbed TLS reference 162implementation where the TF-M Crypto APIs are provided as a remote call across 163a transport channel, which might be represented by a TrustZone boundary (in 164Armv8.x-M systems), by a mailbox channel in heterogeneous systems, e.g. Cortex-A 165+ Cortex-M systems, by an SPM mediated interface, e.g. partition to partition 166calls or, in general, through a mechanism which provides process separation 167between the client and the service sides of the API. 168In this context, the client must always define the Mbed TLS config option 169``MBEDTLS_PSA_CRYPTO_CLIENT``, while the service must always have 170``MBEDTLS_PSA_CRYPTO_SPM``, mainly to avoid symbol clashing at link time between 171the library interface and the ``tfm_crypto_api.c`` interface. When there is a 172component on the service side which is able to identify the client through an 173ID, it is recommended to also define ``MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER`` 174option in order to provide separation in the key space. 175 176Usage of Mbed TLS configuration headers 177~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 178 179Mbed TLS uses two different configuration headers, specified through the setting 180of the ``MBEDTLS_CONFIG_FILE``, i.e. Mbed TLS config, and the setting of 181``MBEDTLS_PSA_CRYPTO_CONFIG_FILE``, i.e. the PSA configuration. In order to be 182able to perform header inclusion for ``psa/crypto.h``, the configuration files 183must be visible to the compilation unit through the include hierarchy. If none of 184the macros are defined, the fall back strategy is to include the default config 185files available in the Mbed TLS repo, i.e. ``include/mbedtls/mbedtls_config.h`` 186and ``include/psa/crypto_config.h``, which contain a set of default values for 187the macros. 188 189Usage of the default header config when using the TF-M Crypto service is highly 190discouraged, mainly because both on the client side and on the service side a 191set of options must always be defined (or undefined), as described in the 192previous section. TF-M provides example _profiles_ which show the options and 193how they should be used on both client and service side of the integration. Note 194that to avoid falling back to the default PSA configuration, the Mbed TLS config 195file must always define the symbol ``MBEDTLS_PSA_CRYPTO_CONFIG``. The symbol to 196enable the Mbed TLS config ``MBEDTLS_CONFIG_FILE`` instead must be available to 197the unit being compiled which is including ``psa/crypto.h``, i.e. passed by the 198build system config stage. 199 200Hardware acceleration 201~~~~~~~~~~~~~~~~~~~~~ 202 203The TF-M Crypto partition must handle all HW related crypto tasks, if the 204platform is capable of offering hardware acceleration or if a complete Secure 205Element is present. The main difference between the two is that a hardware 206accelerator does not store keys but just accelerates operations, while a Secure 207Element is capable of storing keys and the PSA Crypto core running on the host 208must interface with it to store, retrieve or use them for crypto tasks, etc. 209 210There are currently two methods to interface an accelerator into the Crypto 211service, and both rely on the Crypto partition fully owning the Crypto hardware, 212i.e. the memory mapped IO space must be bound the Crypto partition only. Both 213methods are implemented through the capability of the _backend_ library to 214either: 215 2161. Provide a link time mechanism to replace pure SW implementations for algorithms 217 with HW assisted implementations. In this case, the TF-M platform provides some 218 additional HW abstraction through the usage of ``crypto_hw_accelerator_*()`` 219 APIs. This is dubbed the `_ALT` approach and will be soon to be deprecated 220 potentially starting from the release of Mbed TLS 4.0 2212. Provide a cleanly defined interface specification [4]_ to describe the APIs that 222 a driver must expose to the PSA Crypto core in order for the core to be able to 223 offload operations to hardware. This is the preferred method for interfacing with 224 HW. 225 226Both solutions are currently handled at build time (either compilation or linking) 227by Mbed TLS. For details on how to integrate a driver please refer directly to the 228documentation referenced above and to the Mbed TLS repo. 229 230Builtin keys 231~~~~~~~~~~~~ 232 233A particular driver using the interface described in [4]_ is the TF-M Builtin 234Key Loader driver [5]_. The goal of the driver is to make Mbed TLS aware of 235*transparent builtin keys*, i.e. keys which can be read from the core (i.e. not 236fully opaque keys), but that are normally bound to the platform and provisioned 237in it, for which it would be more appropriate to treat them as standard 238*transparent keys*. The concept of *transparent builtin keys* is not defined 239in the spec so it is specifically a non standard extension added by TF-M to the 240Mbed TLS implementation, which might be changed between releases until a standard 241solution is adopted. TF-M patches Mbed TLS on the fly to enable such behaviour 242using patches available in ``lib/ext/mbedcrypto``. Implementations might disable 243the ``tfm_builtin_key_loader`` and then must provide their own alternative storage 244location for all of the TF-M required builtin keys, e.g. by having them stored in 245a Secure Element with a corresponding opaque driver. 246 247Service API description 248----------------------- 249 250The ``Alloc`` and ``Init`` modules implement public APIs which are specific to 251the TF-M Crypto service, and are available only internally to other components 252of the TF-M Crypto partition. For a detailed description of the prototypes 253please refer to the ``tfm_crypto_api.h`` header. 254 255.. table:: Init and Alloc modules APIs 256 :widths: auto 257 258 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 259 | **Function** | **Module** | **Caller** | **Scope** | 260 +================================+==============+=================+======================================================+ 261 | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. It | 262 | | | | does modules initialisation (it initializes the Alloc| 263 | | | | module) and initializes the `backend` library. Being | 264 | | | | the partition enabled for the SFN model, it does not | 265 | | | | implement any IPC specific message handler, instead | 266 | | | | it relies on the SPM being able to schedule SFN | 267 | | | | partitions using the SFN dispatcher with little | 268 | | | | overhead | 269 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 270 | tfm_crypto_sfn() | Init | SPM | Function to handle an SFN request or to interface | 271 | | | | with the message handler when running in IPC model | 272 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 273 | tfm_crypto_init_alloc() | Alloc | Init | Called by ``tfm_crypto_init()``, it initialises the | 274 | | | | internal memory storage in the TF-M Crypto partition | 275 | | | | that the service uses to store multipart operation | 276 | | | | contexts as requested by clients. | 277 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 278 | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart | 279 | | | | operation. It returns an handle to the allocated | 280 | | | | context in secure memory. | 281 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 282 | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context| 283 | | | | of a multipart operation, based on the handle given | 284 | | | | as input. | 285 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 286 | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context | 287 | | | | of a multipart operation, based on the handle given | 288 | | | | as input. | 289 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 290 | tfm_crypto_*_interface() | ``*`` | Init | Interface functions called by the dispatcher to | 291 | | | | service PSA Crypto APIs requests | 292 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 293 294Configuration parameters 295------------------------ 296 297The TF-M Crypto service exposes some configuration parameters to tailor 298the service configuration in terms of supported functionalities and 299hence FLASH/RAM size to meet the requirements of different platforms and 300use cases. These parameters can be provided via CMake parameters during 301the CMake configuration step and as a configuration header to allow the 302configuration of the Mbed TLS library. When using Kconfig they are also 303exported in the Kconfig menus. 304 305.. table:: Configuration parameters table 306 :widths: auto 307 308 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 309 | **Parameter** | **Type** | **Description** | **Default** | 310 +====================================+===========================+================================================================+==========================================================================+ 311 | `CRYPTO_ENGINE_BUF_SIZE` | CMake build | Buffer used by Mbed TLS for its own allocations at runtime. | 8096 (bytes) | 312 | | configuration parameter | This is a buffer allocated in static memory. | | 313 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 314 | `CRYPTO_CONC_OPER_NUM` | CMake build | This parameter defines the maximum number of possible | 8 | 315 | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| | 316 | | | for multi-part operations, that can be allocated simultaneously| | 317 | | | at any time. | | 318 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 319 | `CRYPTO_IOVEC_BUFFER_SIZE` | CMake build | This parameter applies only to IPC model builds. In IPC model, | 5120 (bytes) | 320 | | configuration parameter | during a Service call, input and outputs are allocated | | 321 | | | temporarily in an internal scratch buffer whose size is | | 322 | | | determined by this parameter. | | 323 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 324 | `CRYPTO_STACK_SIZE` | CMake build | Defines the stack size assigned to the crypto partition in | 6912 (bytes) | 325 | | configuration parameter | higher level of isolation configurations (L1 isolation has a | | 326 | | | common stack shared by all partitions) | | 327 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 328 | `CRYPTO_NV_SEED` | CMake build | Uses the Mbed TLS Crypto NV seed feature to provide entropy in | Defined for platforms which don't have ``CRYPTO_HW_ACCELERATOR`` | 329 | | configuration parameter | case there is no HW acceleration providing HW entropy | | 330 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 331 | `CRYPTO_IOVEC_BUFFER_SIZE` | CMake build | Defines the size of scratch buffers to handle input/outputs if | 5120 (bytes) | 332 | | configuration parameter | the Memory Mapped IOVEC feature is not enabled | | 333 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 334 | `CRYPTO_SINGLE_PART_FUNCS_DISABLED`| CMake build | When enabled, only the multipart, i.e. non-integrated APIs will| Not defined (Profile default) | 335 | | configuration parameter | be available in the service | | 336 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 337 | `CRYPTO_*_MODULE_ENABLED` | CMake build | When enabled, the corresponding shim layer module and relative | Defined (Profile default) | 338 | | configuration parameters | APIs are available in the service | | 339 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 340 | `MBEDTLS_CONFIG_FILE` | Configuration header | The Mbed TLS library can be configured to support different | ``lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_default.h`` | 341 | | | algorithms through the usage of a configuration header file | (Profile default) | 342 | | | at build time. This allows for tailoring FLASH/RAM requirements| | 343 | | | for different platforms and use cases. | | 344 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 345 | `MBEDTLS_PSA_CRYPTO_CONFIG_FILE` | Configuration header | This header file specifies which cryptographic mechanisms are | ``lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_default.h`` | 346 | | | available through the PSA API when `MBEDTLS_PSA_CRYPTO_CONFIG` | (Profile default) | 347 | | | is enabled, and is not used when `MBEDTLS_PSA_CRYPTO_CONFIG` is| | 348 | | | disabled. Configuring TF-M always involves having the define | | 349 | | | enabled. | | 350 +------------------------------------+---------------------------+----------------------------------------------------------------+--------------------------------------------------------------------------+ 351 352References 353---------- 354 355.. [1] PSA Certified Crypto API specifications: \ https://arm-software.github.io/psa-api/crypto/ 356.. [2] Using PSA - Getting started in Mbed TLS: \ https://mbed-tls.readthedocs.io/en/latest/getting_started/psa/ 357.. [3] ``Mbed TLS`` repository which holds the reference implementation as a `C` software library: \ https://github.com/Mbed-TLS 358.. [4] PSA Unified Driver Interface for Cryptoprocessors: \ https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/proposed/psa-driver-interface.md 359.. [5] TF-M Builtin Key Loader driver, normally described as :ref:`tfm_builtin_key_loader <tfm-builtin-keys-label>` 360 361-------------- 362 363*Copyright (c) 2019-2024, Arm Limited. All rights reserved.* 364
