diff options
Diffstat (limited to 'docs/integration_guide/services/tfm_crypto_integration_guide.rst')
-rw-r--r-- | docs/integration_guide/services/tfm_crypto_integration_guide.rst | 118 |
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.* |