1Crypto 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 Crypto API 20in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which 21is a reference implementation of the PSA Crypto API. For more details on 22the PSA Crypto API or the Mbed Crypto implementation, please refer 23directly to the ``mbed-crypto`` GitHub repository [1]_ . 24 25The service can be used by other services running in the SPE, or by 26applications running in the NSPE, to provide cryptographic 27functionalities. 28 29Components 30---------- 31 32The TF-M Crypto service is implemented by a number of different software 33components, which are listed below: 34 35.. table:: Components table 36 :widths: auto 37 38 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 39 | **Component name** | **Description** | **Location** | 40 +=============================+===============================================================+======================================================================+ 41 | Client API interface | This module exports the client API of PSA Crypto to the users.| ``./interface/src/tfm_crypto_api.c`` | 42 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 43 | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, | 44 | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` | 45 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 46 | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` | 47 | | during TF-M boot and provides the infrastructure to service | | 48 | | requests when TF-M is built for IPC model. | | 49 | | The dispatching mechanism of IPC requests is based on a look | | 50 | | up table of function pointers. | | 51 | | This design allows for better scalability and support of a | | 52 | | higher number of Secure functions with minimal overhead and | | 53 | | duplication of code. | | 54 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 55 | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` | 56 | | operations in the Secure world. | | 57 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 58 | Service modules | These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key,| ``./secure_fw/partitions/crypto/crypto_aead.c`` | 59 | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/partitions/crypto/crypto_asymmetric.c`` | 60 | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/partitions/crypto/crypto_cipher.c`` | 61 | | They provide parameter sanitation and context retrieval for | ``./secure_fw/partitions/crypto/crypto_key_derivation.c`` | 62 | | multipart operations, and dispatching to the corresponding | ``./secure_fw/partitions/crypto/crypto_hash.c`` | 63 | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/partitions/crypto/crypto_key.c`` | 64 | | functionality. | ``./secure_fw/partitions/crypto/crypto_mac.c`` | 65 | | | ''./secure_fw/partitions/crypto/crypto_key_management.c'' | 66 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 67 | Manifest | The manifest file is a description of the service components. | ``./secure_fw/partitions/crypto/manifest.yaml`` | 68 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 69 | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/partitions/crypto/CMakeLists.inc`` | 70 | | build the service as part of the Secure FW build. The service | ``./secure_fw/partitions/crypto/CMakeLists.txt`` | 71 | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` | 72 | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/partitions/crypto/tfm_crypto_api.h`` | 73 | | library as part of the Secure FW build process and archive it | ``./secure_fw/partitions/crypto/tfm_crypto_signal.h`` | 74 | | with the static library of the Crypto service. | ``./secure_fw/partitions/crypto/spe_crypto.h`` | 75 | | The headers are used to export the public prototypes of the | | 76 | | functions in the Service modules ``tfm_crypto_api.h``, and | | 77 | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | | 78 | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | | 79 | | which the service handler waits for requests when the service | | 80 | | is built for IPC model. | | 81 | | The header available in the interface, ``tfm_crypto_defs.h`` | | 82 | | , contains types and defines for building the NSPE interface | | 83 | | as part of a Non-Secure application. | | 84 | | Finally, the ``crypto_spe.h`` header is used during the | | 85 | | build of the Mbed Crypto library, when the Mbed Crypto config | | 86 | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | | 87 | | custom prefix to the PSA API symbols so that duplication of | | 88 | | symbol names is avoided. | | 89 | | The prefix used for the PSA API symbols of the Mbed Crypto | | 90 | | library is chosen to be ``mbedcrypto__``. | | 91 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 92 | Documentation | The integration guide contains the description of the TF-M | ``./user_guides/services/tfm_crypto_integration_guide.rst`` | 93 | | Crypto service modules and interfaces. | | 94 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+ 95 96The interaction between the different components is described by the 97following block diagram: 98 99.. figure:: /design_docs/media/tfm_crypto_design.png 100 101 Block diagram of the different components of the TF-M Crypto service. A 102 dotted line is used to indicate the interaction with a library. 103 104Note: in IPC model, the interaction between components is slightly 105different, as the Service modules are not called directly through the 106TF-M Secure Partition Manager but through the IPC handler which resides 107in the Init module. 108 109Service API description 110----------------------- 111 112Most of the APIs exported by the TF-M Crypto service (i.e. from the Service 113modules) have a direct correspondence with the PSA Crypto API. The Alloc and 114Init modules instead export some APIs which are specific to the TF-M Crypto 115service, and are available only to the Service modules or the SPM. For a 116detailed description of the prototypes please refer to the ``tfm_crypto_api.h`` 117header. 118 119.. table:: Init and Alloc modules APIs 120 :widths: auto 121 122 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 123 | **Function** | **Module** | **Caller** | **Scope** | 124 +================================+==============+=================+======================================================+ 125 | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC | 126 | | | | model, it calls the IPC service request handler. | 127 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 128 | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the | 129 | | | | concurrent operation contexts storage area. | 130 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 131 | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart | 132 | | | | operation. It returns an handle to the allocated | 133 | | | | context in secure memory. | 134 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 135 | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context| 136 | | | | of a multipart operation, based on the handle given | 137 | | | | as input. | 138 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 139 | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context | 140 | | | | of a multipart operation, based on the handle given | 141 | | | | as input. | 142 +--------------------------------+--------------+-----------------+------------------------------------------------------+ 143 144Configuration parameters 145------------------------ 146 147The TF-M Crypto service exposes some configuration parameters to tailor 148the service configuration in terms of supported functionalities and 149hence FLASH/RAM size to meet the requirements of different platforms and 150use cases. These parameters can be provided via CMake parameters during 151the CMake configuration step and as a configuration header to allow the 152configuration of the Mbed Crypto library. 153 154.. table:: Configuration parameters table 155 :widths: auto 156 157 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 158 | **Parameter** | **Type** | **Description** | **Scope** | **Default** | 159 +====================================+===========================+================================================================+=========================================+============================================================================+ 160 | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 8096 (bytes) | 161 | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | | 162 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 163 | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 | 164 | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and key deriv)| use case and platform requirements. | | 165 | | | for multi-part operations, that can be allocated simultaneously| | | 166 | | | at any time. | | | 167 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 168 | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC model builds. In IPC model, | To be configured based on the desired | 5120 (bytes) | 169 | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | | 170 | | | temporarily in an internal scratch buffer whose size is | | | 171 | | | determined by this parameter. | | | 172 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 173 | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_default.h`` | 174 | | | algorithms through the usage of a a configuration header file | application and platform requirements. | | 175 | | | at build time. This allows for tailoring FLASH/RAM requirements| | | 176 | | | for different platforms and use cases. | | | 177 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 178 | ``MBEDTLS_PSA_CRYPTO_CONFIG_FILE`` | Configuration header | This header file specifies which cryptographic mechanisms are | To be configured based on the | ``./lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_default.h`` | 179 | | | available through the PSA API when #MBEDTLS_PSA_CRYPTO_CONFIG | application and platform requirements. | | 180 | | | is enabled, and is not used when #MBEDTLS_PSA_CRYPTO_CONFIG is | | | 181 | | | disabled. | | | 182 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+ 183 184References 185---------- 186 187.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/Mbed-TLS 188 189 190-------------- 191 192*Copyright (c) 2019-2022, Arm Limited. All rights reserved.* 193
