1################################
2Crypto Service Integration Guide
3################################
4
5************
6Introduction
7************
8TF-M Crypto service allows application to use cryptography primitives such as
9symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
10authenticated encryption with associated data (AEAD).
11
12**************
13Code structure
14**************
15The PSA interfaces for the Crypto service are located in ``interface/include``.
16The only header to be included by applications that want to use functions from
17the PSA API is ``psa/crypto.h``.
18The TF-M Crypto service source files are located in
19``secure_fw/partitions/crypto``.
20
21PSA interfaces
22==============
23The TF-M Crypto service exposes the PSA interfaces detailed in the header
24``psa/crypto.h``. This header, in turn, includes several other headers which
25are not meant to be included directly by user applications. For a detailed
26description of the PSA API interface, please refer to the comments in the
27``psa/crypto.h`` header itself.
28
29Service source files
30====================
31- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
32  operations
33- ``crypto_hash.c`` : This module handles requests for hashing operations
34- ``crypto_mac.c`` : This module handles requests for MAC operations
35- ``crypto_aead.c`` : This module handles requests for AEAD operations
36- ``crypto_key_derivation.c`` : This module handles requests for key derivation
37  related operations
38- ``crypto_key_management.c`` : This module handles requests for key management
39  related operations
40- ``crypto_key.c`` : This module handles requests for key backend operations,
41  including key attributes switch between caller and service.
42- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
43  cryptographic operations
44- ``crypto_init.c`` : This module provides basic functions to initialise the
45  secure service during TF-M boot. When the service is built for IPC model
46  compatibility, this layer handles as well the connection requests and the
47  proper dispatching of requests to the corresponding functions, and it holds
48  the internal buffer used to allocate temporarily the IOVECs needed. The size
49  of this buffer is controlled by the ``CRYPTO_IOVEC_BUFFER_SIZE`` define.
50  This module also provides a static buffer which is used by the Mbed Crypto
51  library for its own allocations. The size of this buffer is controlled by
52  the ``CRYPTO_ENGINE_BUF_SIZE`` define
53- ``crypto_alloc.c`` : This module is required for the allocation and release of
54  crypto operation contexts in the SPE. The ``CRYPTO_CONC_OPER_NUM``,
55  defined in this file, determines how many concurrent contexts are supported
56  for multipart operations (8 for the current implementation). For multipart
57  cipher/hash/MAC/generator operations, a context is associated to the handle
58  provided during the setup phase, and is explicitly cleared only following a
59  termination or an abort
60- ``tfm_crypto_api.c`` : This module implements the PSA Crypto API
61  client interface exposed to users.
62- ``tfm_crypto_api.c`` :  This module is contained in ``interface/src`` and
63  implements the PSA Crypto API client interface exposed to the  Non-Secure
64  Processing Environment.
65- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
66  Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
67  Small by default.
68
69****************************
70Crypto Backend configuration
71****************************
72
73The Crypto service can use either a hardware crypto accelerator backend like
74CC-312 or a software crypto library which by default is MbedTLS.
75
76If using MbedTLS as backend, then the library configuration is supplied using
77the ``TFM_MBEDCRYPTO_CONFIG_PATH`` and ``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH``
78cmake option.
79
80Platforms can specify an extra config file by setting the
81``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
82around the ``MBEDTLS_USER_CONFIG_FILE`` option).  This is preferred for platform
83configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` and
84``TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH`` as it does not interfere with
85config changes due to TFM Profile.
86
87.. Note::
88
89    The default entropy source configured for MbedTLS is
90    MBEDTLS_ENTROPY_NV_SEED with unique seed. For production devices,
91    it can also select a hardware entropy source via
92    MBEDTLS_ENTROPY_HARDWARE_ALT
93
94**************************************
95Other Crypto Service Build Definitions
96**************************************
97- ``CRYPTO_STACK_SIZE``- Defines the stack size of the Crypto Secure Partition. This
98  value mainly depends on other crypto service configurations, the build type(debug,
99  release and minisizerel) and compiler.
100
101**************************
102Crypto service integration
103**************************
104In this section, a brief description of the required flow of operation for the
105functionalities exported by the PSA Crypto interface is given, with particular
106focus on the TF-M Crypto service specific operations. For the details of the
107generic PSA Crypto interface operations, please refer directly to the header
108``psa/crypto.h``.
109
110Most of the PSA Crypto multipart APIs require an operation context to be
111allocated by the application and then to be passed as a pointer during the
112following API calls. These operation contexts are of four main types described
113below:
114
115- ``psa_key_derivation_operation_t`` - Operation context for key derivation
116- ``psa_hash_operation_t`` - Operation context for multipart hash operations
117- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
118- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
119
120The user applications are not allowed to make any assumption about the original
121types behind these typedefs, which are defined inside ``psa/crypto.h``.
122In the scope of the TF-M Crypto service, these types are regarded as handles to
123the corresponding implementation defined structures which are stored in the
124Secure world.
125
126--------------
127
128*Copyright (c) 2018-2022, Arm Limited. All rights reserved.*
129