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