1.. _tfm-crypto-integration-guide-label:
2
3################################
4Crypto Service Integration Guide
5################################
6
7************
8Introduction
9************
10The TF-M Crypto service allows Non Secure world applications and Secure
11services to use cryptographic functionalities such as symmetric ciphering,
12message signing and verification, asymmetric encryption and decryption,
13cryptographic hashes, message authentication codes (MACs), key derivation and
14agreement, authenticated encryption with associated data (AEAD). It exposes the
15PSA Crypto APIs [1]_.
16
17.. _components-label:
18
19The secure service resides in the Crypto partition as a single entry point and
20is made of different components:
21
22 - An interface layer that exposes the PSA Crypto API to either NS or S entities
23   and is implemented in ``interface/src/tfm_crypto_api.c``. The interface is
24   based on the Uniform Secure Service Signature and communicates with the
25   Secure Partition Manager available in TF-M
26 - An init module ``secure_fw/partitions/crypto/crypto_init.c`` that implements
27   functionalities requested by TF-M during the initialisation phase, and an API
28   dispatcher that at runtime receives the requests from the interface and
29   dispatches them to the component that processes that particular API request
30 - A set of components that process cryptographic API requests, each component
31   dispatching to a subset of functionalities, i.e. AEAD, Asymmetric, Ciphering,
32   Hashing, Key derivation, Key management, MACs, and Random Number Generation
33 - An alloc module ``secure_fw/partitions/crypto/crypto_alloc.c`` that manages
34   the partition secure memory, storing multipart application contexts, input /
35   outputs of the APIs being requested, inaccessible from NS or other secure
36   partitions
37 - A library abstraction module ``secure_fw/partitions/crypto/crypto_library.c``
38   which is used to abstract the details of the cryptographic library used by
39   the service *backend* to provide the actual implementation of the crypto
40   functionalities. The backend library must expose the PSA Crypto APIs, and
41   must provide support to encode *key ownership* into key identifiers. This is
42   not standardized by the PSA Crypto APIs so it must be provided as an
43   extension to the APIs. The backend library also needs to provide the
44   subsystem for key storage and retrieval, and, in case, the interface to the
45   cryptographic accelerator of the underlying platform, using the PSA
46   cryptoprocessor driver interface specification [2]_. For this reason, it must
47   provide a mechanism to access platform *builtin* keys, and permanent key
48   slots using the
49   :ref:`TF-M Internal Trusted Storage (ITS) service <its-introduction-label>`,
50   if available.
51
52**************
53Code structure
54**************
55The PSA interfaces for the Crypto service are located in ``interface/include``.
56The only header to be included by applications that want to use functions from
57the PSA API is ``psa/crypto.h``. The TF-M Crypto service source files are
58located in ``secure_fw/partitions/crypto``.
59
60PSA interfaces
61==============
62The TF-M Crypto service exposes the PSA interfaces detailed in the header
63``psa/crypto.h``. This header, in turn, includes several other headers which
64are not meant to be included directly by user applications. For a detailed
65description of the PSA API interface, please refer to the comments in the
66``psa/crypto.h`` header itself.
67
68Service source files
69====================
70A brief description of what is implemented by each source file is as below:
71
72 - ``crypto_cipher.c`` : Dispatcher for symmetric crypto operations
73 - ``crypto_hash.c`` : Dispatcher for hash operations
74 - ``crypto_mac.c`` : Dispatcher for MAC operations
75 - ``crypto_aead.c`` : dispatcher for AEAD operations
76 - ``crypto_key_derivation.c`` : Dispatcher for key derivation and key agreement
77   operations
78 - ``crypto_key_management.c`` : Dispatcher for key management operations
79   towards the key slot management system provided by the backend library
80 - ``crypto_rng.c`` : Dispatcher for the random number generation requests
81 - ``crypto_asymmetric.c`` : Dispatcher for message signature/verification and
82   encryption/decryption using asymmetric crypto
83 - ``crypto_init.c`` : Init module for the service. The modules stores also the
84   internal buffer used to allocate temporarily the IOVECs needed, which is not
85   required in case of SFN model. The size of this buffer is controlled by the
86   ``CRYPTO_IOVEC_BUFFER_SIZE`` config define
87 - ``crypto_library.c`` : Library abstractions to interface the dispatchers
88   towards the underlying library providing *backend* crypto functions.
89   Currently this only supports the Mbed TLS library. In particular, the mbed
90   TLS library requires to provide a static buffer to be used as heap for its
91   internal allocation. The size of this buffer is controlled by the
92   ``CRYPTO_ENGINE_BUF_SIZE`` config define
93 - ``crypto_alloc.c`` : Takes care of storing multipart operation contexts in a
94   secure memory not visible outside of the crypto service. The
95   ``CRYPTO_CONC_OPER_NUM`` config define determines how many concurrent
96   contexts are supported at once. In a multipart operation, the client view of
97   the contexts is much simpler (i.e. just an handle), and the Alloc module
98   keeps track of the association between handles and contexts
99 - ``tfm_crypto_api.c`` :  This module is contained in ``interface/src`` and
100   implements the PSA Crypto API client interface exposed to both S/NS clients.
101   This module allows a configuration option ``CONFIG_TFM_CRYPTO_API_RENAME``
102   to be set to 1 in case the NS environment or integrators want to rename the
103   API symbols exported by the TF-M Crypto service. The renaming adds a default
104   prefix, ``tfm_crypto__`` to all functions. The prefix can be changed editing
105   the interface file. This config option is for the NS environment or
106   integration setup only, hence it is not accessible through the TF-M config
107 - ``tfm_mbedcrypto_alt.c`` : This module is specific to the Mbed TLS [3]_
108   library integration and provides some alternative implementation of Mbed TLS
109   APIs that can be used when a optimised profile is chosen. Through the
110   ``_ALT`` mechanism it is possible to replace at link time default
111   implementations available in Mbed TLS with the ones available in this file
112
113   .. Note::
114     The ``_ALT`` mechanism will be deprecated in future releases of the Mbed
115     TLS library
116
117***************************************
118Considerations on service configuration
119***************************************
120
121Crypto *backend* library configuration
122======================================
123The TF-M Crypto service relies on a cryptographic library to provide the
124functionalities specific by the PSA Crypto API spec and the PSA cryptoprocessor
125driver interface spec. At the moment, the only supported library is mbed
126TLS [3]_.
127
128The configuration of the backend library is supplied using the
129``TFM_MBEDCRYPTO_CONFIG_PATH`` and ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``
130config option that point to configuration headers following the legacy Mbed TLS
131configuration scheme or the new PSA based configuration scheme.
132
133Platforms can specify an extra config file by setting the
134``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
135around the ``MBEDTLS_USER_CONFIG_FILE`` option).  This is preferred for platform
136configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` and
137``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH`` as it does not interfere with
138config changes due to TFM Profile.
139
140.. Note::
141
142    The default entropy source configured for Mbed TLS is
143    ``MBEDTLS_ENTROPY_NV_SEED`` with a unique seed. For production devices, an
144    alternative hardware entropy source can be specified using the config option
145    ``MBEDTLS_ENTROPY_HARDWARE_ALT``
146
147.. Note::
148    Starting from Mbed TLS 3.3.0, the Python package ``jsonschema`` must be
149    available when building as it is required by the autogen framework for the
150    driver integrations into the PSA Crypto core and driver wrapper modules
151
152Crypto service build time options
153=================================
154
155  - ``CRYPTO_STACK_SIZE`` : Defines the stack size of the Crypto Secure
156    Partition. This value might depend on several parameters such as the build
157    type, the compiler being used, the cryptographic functionalities that are
158    enabled at build time
159  - ``CRYPTO_<COMPONENT>_MODULE_ENABLED`` : A series of defines, one per each
160    ``<COMPONENT>`` that processes cryptographic operations, that are used to
161    disable modules at build time. Each define corresponds to a component as
162    described in :ref:`the components list <components-label>`.
163
164
165Crypto service *builtin* keys integration
166=========================================
167A detailed description of how the service interacts with *builtin* keys is
168available in the ``tfm_builtin_key_loader``
169:ref:`design document <tfm-builtin-keys-label>`.
170
171.. Note::
172
173    The crypto service integration with builtin keys relies on implementation
174    details of Mbed TLS that are not standardized in the spec and might change
175    between releases due to ongoing work [4]_
176
177
178References
179----------
180
181.. [1] PSA Crypto APIs: \ https://armmbed.github.io/mbed-crypto/html/
182.. [2] PSA cryptoprocessor driver interface: \ https://github.com/Mbed-TLS/TF-PSA-Crypto/blob/development/docs/proposed/psa-driver-interface.md
183.. [3] Mbed TLS library: \ https://www.trustedfirmware.org/projects/mbed-tls/
184.. [4] Interface for platform keys:  `https://github.com/ARM-software/psa-crypto-api/issues/550` (private)
185
186
187--------------
188
189*Copyright (c) 2018-2023, Arm Limited. All rights reserved.*
190