TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / TF-M / trusted-firmware-m / b3f64662e119d0cc715561485cc0b5a68aa4491a / . / docs / design_docs / services / tfm_crypto_design.rst
blob: 71068490524d829ae55d8e2bd50884b9a190f721 [file] [log] [blame]
Galanakis, Minos41f85972019-09-30 15:56:40 +0100[diff] [blame]1Crypto Service design
2=====================
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]3
4:Author: Antonio de Angelis
5:Organization: Arm Limited
6:Contact: Antonio de Angelis <antonio.deangelis@arm.com>
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 +=============================+===============================================================+======================================================================+
Summer Qind23bbb32022-10-18 15:30:06 +0800[diff] [blame]41 | Client API interface | This module exports the client API of PSA Crypto to the users.| ``./interface/src/tfm_crypto_api.c`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Ken Liu738a4b02020-06-04 14:52:38 +0800[diff] [blame]46 | Init module | This module handles the initialisation of the service objects | ``./secure_fw/partitions/crypto/crypto_init.c`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]47 | | during TF-M boot and provides the infrastructure to service | |
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]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. | |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Ken Liu738a4b02020-06-04 14:52:38 +0800[diff] [blame]55 | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/partitions/crypto/crypto_alloc.c`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]56 | | operations in the Secure world. | |
57 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Ken Liu738a4b02020-06-04 14:52:38 +0800[diff] [blame]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`` |
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]65 | | | ''./secure_fw/partitions/crypto/crypto_key_management.c'' |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]66 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Summer Qin2db78c82022-10-10 17:17:44 +0800[diff] [blame]67 | Manifest | The manifest file is a description of the service components. | ``./secure_fw/partitions/crypto/manifest.yaml`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]68 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Ken Liu738a4b02020-06-04 14:52:38 +0800[diff] [blame]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`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]71 | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` |
Ken Liu738a4b02020-06-04 14:52:38 +0800[diff] [blame]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`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 | |
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]80 | | is built for IPC model. | |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
Anton Komlev3356ba32022-03-31 22:02:11 +0100[diff] [blame]92 | Documentation | The integration guide contains the description of the TF-M | ``./user_guides/services/tfm_crypto_integration_guide.rst`` |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]93 | | Crypto service modules and interfaces. | |
94 +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
95
96The interaction between the different components is described by the
97following block diagram:
98
Anton Komlevb3f64662023-01-28 11:53:05 +0000[diff] [blame^]99.. figure:: /design_docs/media/tfm_crypto_design.png
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]104Note: in IPC model, the interaction between components is slightly
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]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.
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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 |
Summer Qin179cb702021-09-08 11:18:24 +0800[diff] [blame]126 | | | | model, it calls the IPC service request handler. |
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]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
Summer Qin7c0d8d32021-12-17 15:43:08 +0800[diff] [blame]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 +------------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------------------------------+
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]183
184References
185----------
186
Anton Komlevfb835402022-08-09 13:04:04 +0100[diff] [blame]187.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/Mbed-TLS
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]188
Antonio de Angelis0d98a5f2019-05-07 16:47:58 +0100[diff] [blame]189
190--------------
191
Summer Qin7c0d8d32021-12-17 15:43:08 +0800[diff] [blame]192*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*