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