aboutsummaryrefslogtreecommitdiff
path: root/docs/integration_guide/services/tfm_crypto_integration_guide.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/integration_guide/services/tfm_crypto_integration_guide.rst')
-rw-r--r--docs/integration_guide/services/tfm_crypto_integration_guide.rst118
1 files changed, 118 insertions, 0 deletions
diff --git a/docs/integration_guide/services/tfm_crypto_integration_guide.rst b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
new file mode 100644
index 0000000000..a124bdf491
--- /dev/null
+++ b/docs/integration_guide/services/tfm_crypto_integration_guide.rst
@@ -0,0 +1,118 @@
+################################
+Crypto Service Integration Guide
+################################
+
+************
+Introduction
+************
+TF-M Crypto service allows application to use cryptography primitives such as
+symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and
+authenticated encryption with associated data (AEAD).
+
+**************
+Code structure
+**************
+The PSA interfaces for the Crypto service are located in ``interface/include``.
+The only header to be included by applications that want to use functions from
+the PSA API is ``psa/crypto.h``.
+The TF-M Crypto service source files are located in
+``secure_fw/partitions/crypto``.
+
+PSA interfaces
+==============
+The TF-M Crypto service exposes the PSA interfaces detailed in the header
+``psa/crypto.h``. This header, in turn, includes several other headers which
+are not meant to be included directly by user applications. For a detailed
+description of the PSA API interface, please refer to the comments in the
+``psa/crypto.h`` header itself.
+
+Service source files
+====================
+- ``crypto_cipher.c`` : This module handles requests for symmetric cipher
+ operations
+- ``crypto_hash.c`` : This module handles requests for hashing operations
+- ``crypto_mac.c`` : This module handles requests for MAC operations
+- ``crypto_aead.c`` : This module handles requests for AEAD operations
+- ``crypto_key_derivation.c`` : This module handles requests for key derivation
+ related operations
+- ``crypto_key.c`` : This module handles requests for key related operations
+- ``crypto_asymmetric.c`` : This module handles requests for asymmetric
+ cryptographic operations
+- ``crypto_init.c`` : This module provides basic functions to initialise the
+ secure service during TF-M boot. When the service is built for IPC mode
+ compatibility, this layer handles as well the connection requests and the
+ proper dispatching of requests to the corresponding functions, and it holds
+ the internal buffer used to allocate temporarily the IOVECs needed. The size
+ of this buffer is controlled by the ``TFM_CRYPTO_IOVEC_BUFFER_SIZE`` define.
+ This module also provides a static buffer which is used by the Mbed Crypto
+ library for its own allocations. The size of this buffer is controlled by
+ the ``TFM_CRYPTO_ENGINE_BUF_SIZE`` define
+- ``crypto_alloc.c`` : This module is required for the allocation and release of
+ crypto operation contexts in the SPE. The ``TFM_CRYPTO_CONC_OPER_NUM``,
+ defined in this file, determines how many concurrent contexts are supported
+ for multipart operations (8 for the current implementation). For multipart
+ cipher/hash/MAC/generator operations, a context is associated to the handle
+ provided during the setup phase, and is explicitly cleared only following a
+ termination or an abort
+- ``tfm_crypto_secure_api.c`` : This module implements the PSA Crypto API
+ client interface exposed to the Secure Processing Environment
+- ``tfm_crypto_api.c`` : This module is contained in ``interface/src`` and
+ implements the PSA Crypto API client interface exposed to the Non-Secure
+ Processing Environment.
+- ``tfm_mbedcrypto_alt.c`` : This module contains alternative implementations of
+ Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile
+ Small by default.
+
+****************************
+Crypto Backend configuration
+****************************
+
+The Crypto service can use either a hardware crypto accelerator backend like
+CC-312 or a software crypto library which by default is MbedTLS.
+
+If using MbedTLS as backend, then the library configuration is supplied using
+the ``TFM_MBEDCRYPTO_CONFIG_PATH`` cmake option.
+
+Platforms can specify an extra config file by setting the
+``TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH`` variable (which is a wrapper
+around the ``MBEDTLS_USER_CONFIG_FILE`` option). This is preferred for platform
+configuration over ``TFM_MBEDCRYPTO_CONFIG_PATH`` as it does not interfere with
+config changes due to TFM Profile.
+
+.. Note::
+
+ The default entropy source configured for MbedTLS is
+ MBEDTLS_TEST_NULL_ENTROPY and this does not provide randomness
+ for production devices. It is required for production devices to select
+ either a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT or
+ provision a unique seed for the device during production and use the
+ MBEDTLS_ENTROPY_NV_SEED option.
+
+**************************
+Crypto service integration
+**************************
+In this section, a brief description of the required flow of operation for the
+functionalities exported by the PSA Crypto interface is given, with particular
+focus on the TF-M Crypto service specific operations. For the details of the
+generic PSA Crypto interface operations, please refer directly to the header
+``psa/crypto.h``.
+
+Most of the PSA Crypto multipart APIs require an operation context to be
+allocated by the application and then to be passed as a pointer during the
+following API calls. These operation contexts are of four main types described
+below:
+
+- ``psa_key_derivation_operation_t`` - Operation context for key derivation
+- ``psa_hash_operation_t`` - Operation context for multipart hash operations
+- ``psa_mac_operation_t`` - Operation context for multipart MAC operations
+- ``psa_cipher_operation_t`` - Operation context for multipart cipher operations
+
+The user applications are not allowed to make any assumption about the original
+types behind these typedefs, which are defined inside ``psa/crypto.h``.
+In the scope of the TF-M Crypto service, these types are regarded as handles to
+the corresponding implementation defined structures which are stored in the
+Secure world.
+
+--------------
+
+*Copyright (c) 2018-2020, Arm Limited. All rights reserved.*