Docs: TF-M Crypto service Design
This patch adds the design document for the TF-M
Crypto service.
Change-Id: I60ee575a9891c1bf4915345199a328120a276e12
Signed-off-by: Antonio de Angelis <antonio.deangelis@arm.com>
diff --git a/docs/design_documents/tfm_crypto_design.rst b/docs/design_documents/tfm_crypto_design.rst
new file mode 100644
index 0000000..c0cf769
--- /dev/null
+++ b/docs/design_documents/tfm_crypto_design.rst
@@ -0,0 +1,198 @@
+TF-M Crypto Service design
+==========================
+
+:Author: Antonio de Angelis
+:Organization: Arm Limited
+:Contact: Antonio de Angelis <antonio.deangelis@arm.com>
+:Status: Accepted
+
+.. contents:: Table of Contents
+
+Abstract
+--------
+
+This document describes the design of the TF-M Cryptographic Secure Service
+(in short, TF-M Crypto service).
+
+Introduction
+------------
+
+The TF-M Crypto service provides an implementation of the PSA Crypto API
+in a PSA RoT secure partition in TF-M. It is based on Mbed Crypto, which
+is a reference implementation of the PSA Crypto API. For more details on
+the PSA Crypto API or the Mbed Crypto implementation, please refer
+directly to the ``mbed-crypto`` GitHub repository [1]_ .
+
+The service can be used by other services running in the SPE, or by
+applications running in the NSPE, to provide cryptographic
+functionalities.
+
+Components
+----------
+
+The TF-M Crypto service is implemented by a number of different software
+components, which are listed below:
+
+.. table:: Components table
+ :widths: auto
+
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | **Component name** | **Description** | **Location** |
+ +=============================+===============================================================+======================================================================+
+ | SPE client API interface | This module exports the client API of PSA Crypto to the other | ``./secure_fw/services/crypto/tfm_crypto_secure_api.c`` |
+ | | services available in TF-M. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | NSPE client API interface | This module exports the client API of PSA Crypto to the NSPE | ``./interface/src/tfm_crypto_api.c`` |
+ | | (i.e. to the applications). | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Mbed Crypto | The Mbed Crypto library is used in the service as a | Needed as dependency at the same level of the TF-M folder, |
+ | | cryptographic library exposing the PSA Crypto API interface. | i.e. ``../mbed-crypto`` |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Init module | This module handles the initialisation of the service objects | ``./secure_fw/services/crypto/crypto_init.c`` |
+ | | during TF-M boot and provides the infrastructure to service | |
+ | | requests when TF-M is built for IPC mode. | |
+ | | Due to the fact that the functions available in the Service | |
+ | | modules use the Uniform Signature prototype [2]_ , the | |
+ | | dispatching mechanism of IPC requests is based on a look up | |
+ | | table of function pointers. | |
+ | | This design allows for better scalability and support of a | |
+ | | higher number of Secure functions with minimal overhead and | |
+ | | duplication of code. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Alloc module | This module handles the allocation of contexts for multipart | ``./secure_fw/services/crypto/crypto_alloc.c`` |
+ | | operations in the Secure world. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Service modules | These modules (AEAD, Asymmetric, Cipher, Generator, Hash, Key,| ``./secure_fw/services/crypto/crypto_aead.c`` |
+ | | MAC) represent a thin layer which is in charge of servicing | ``./secure_fw/services/crypto/crypto_asymmetric.c`` |
+ | | the calls from the SPE/NSPE client API interfaces. | ``./secure_fw/services/crypto/crypto_cipher.c`` |
+ | | They provide parameter sanitation and context retrieval for | ``./secure_fw/services/crypto/crypto_generator.c`` |
+ | | multipart operations, and dispatching to the corresponding | ``./secure_fw/services/crypto/crypto_hash.c`` |
+ | | library function exposed by Mbed Crypto for the desired | ``./secure_fw/services/crypto/crypto_key.c`` |
+ | | functionality. | ``./secure_fw/services/crypto/crypto_mac.c`` |
+ | | All the functions in the Service modules are based on the | |
+ | | Uniform Signature prototype [2]_ . | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Manifest | The manifest file is a description of the service components | ``./secure_fw/services/crypto/manifest.yaml`` |
+ | | for both library mode and IPC mode. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | CMake files and headers | The CMake files are used by the TF-M CMake build system to | ``./secure_fw/services/crypto/CMakeLists.inc`` |
+ | | build the service as part of the Secure FW build. The service | ``./secure_fw/services/crypto/CMakeLists.txt`` |
+ | | is built as a static library (``tfm_crypto.a``). | ``./interface/include/tfm_crypto_defs.h`` |
+ | | The build system allows to build as well the Mbed Crypto | ``./secure_fw/services/crypto/tfm_crypto_api.h`` |
+ | | library as part of the Secure FW build process and archive it | ``./secure_fw/services/crypto/tfm_crypto_signal.h`` |
+ | | with the static library of the Crypto service. | ``./secure_fw/services/crypto/spe_crypto.h`` |
+ | | The headers are used to export the public prototypes of the | |
+ | | functions in the Service modules ``tfm_crypto_api.h``, and | |
+ | | to provide the necessary defines (i.e. ``TFM_CRYPTO_SIG``). | |
+ | | In particular ``TFM_CRYPTO_SIG`` identifies the signal on | |
+ | | which the service handler waits for requests when the service | |
+ | | is built for IPC mode. | |
+ | | The header available in the interface, ``tfm_crypto_defs.h`` | |
+ | | , contains types and defines for building the NSPE interface | |
+ | | as part of a Non-Secure application. | |
+ | | Finally, the ``crypto_spe.h`` header is used during the | |
+ | | build of the Mbed Crypto library, when the Mbed Crypto config | |
+ | | option ``MBEDTLS_PSA_CRYPTO_SPM`` is defined, to add a | |
+ | | custom prefix to the PSA API symbols so that duplication of | |
+ | | symbol names is avoided. | |
+ | | The prefix used for the PSA API symbols of the Mbed Crypto | |
+ | | library is chosen to be ``mbedcrypto__``. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+ | Documentation | The integration guide contains the description of the TF-M | ``./docs/user_guides/services/tfm_crypto_integration_guide.rst`` |
+ | | Crypto service modules and interfaces. | |
+ +-----------------------------+---------------------------------------------------------------+----------------------------------------------------------------------+
+
+The interaction between the different components is described by the
+following block diagram:
+
+.. figure:: media/tfm_crypto_design.png
+
+ Block diagram of the different components of the TF-M Crypto service. A
+ dotted line is used to indicate the interaction with a library.
+
+Note: in IPC mode, the interaction between components is slightly
+different, as the Service modules are not called directly through the
+TF-M Secure Partition Manager but through the IPC handler which resides
+in the Init module.
+
+Service API description
+-----------------------
+
+Most of the APIs exported by the TF-M Crypto service (i.e. from the Service
+modules) is based on the Uniform Signature prototypes [2]_ and have a direct
+correspondence with the PSA Crypto API. The Alloc and Init modules instead
+export some APIs which are specific to the TF-M Crypto service, and are
+available only to the Service modules or the SPM. For a detailed description
+of the prototypes please refer to the ``tfm_crypto_api.h`` header.
+
+.. table:: Init and Alloc modules APIs
+ :widths: auto
+
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | **Function** | **Module** | **Caller** | **Scope** |
+ +================================+==============+=================+======================================================+
+ | tfm_crypto_init() | Init | SPM | Called during TF-M boot for initialisation. In IPC |
+ | | | | mode, it calls the IPC service request handler. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_init_alloc() | Alloc | Init | Called by tfm_crypto_init(), it initialises the |
+ | | | | concurrent operation contexts storage area. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_alloc() | Alloc | Service modules | It allocates a new operation context for a multipart |
+ | | | | operation. It returns an handle to the allocated |
+ | | | | context in secure memory. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_lookup() | Alloc | Service modules | It retrieves a previously allocated operation context|
+ | | | | of a multipart operation, based on the handle given |
+ | | | | as input. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+ | tfm_crypto_operation_release() | Alloc | Service modules | It releases a previously allocated operation context |
+ | | | | of a multipart operation, based on the handle given |
+ | | | | as input. |
+ +--------------------------------+--------------+-----------------+------------------------------------------------------+
+
+Configuration parameters
+------------------------
+
+The TF-M Crypto service exposes some configuration parameters to tailor
+the service configuration in terms of supported functionalities and
+hence FLASH/RAM size to meet the requirements of different platforms and
+use cases. These parameters can be provided via CMake parameters during
+the CMake configuration step and as a configuration header to allow the
+configuration of the Mbed Crypto library.
+
+.. table:: Configuration parameters table
+ :widths: auto
+
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | **Parameter** | **Type** | **Description** | **Scope** | **Default** |
+ +===============================+===========================+================================================================+=========================================+====================================================+
+ | ``CRYPTO_ENGINE_BUF_SIZE`` | CMake build | Buffer used by Mbed Crypto for its own allocations at runtime. | To be configured based on the desired | 1024 (bytes) |
+ | | configuration parameter | This is a buffer allocated in static memory. | use case and application requirements. | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``CRYPTO_CONC_OPER_NUM`` | CMake build | This parameter defines the maximum number of possible | To be configured based on the desire | 8 |
+ | | configuration parameter | concurrent operation contexts (cipher, MAC, hash and generator)| use case and platform requirements. | |
+ | | | for multi-part operations, that can be allocated simultaneously| | |
+ | | | at any time. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``CRYPTO_IOVEC_BUFFER_SIZE`` | CMake build | This parameter applies only to IPC mode builds. In IPC mode, | To be configured based on the desired | 1024 (bytes) |
+ | | configuration parameter | during a Service call, input and outputs are allocated | use case and application requirements. | |
+ | | | temporarily in an internal scratch buffer whose size is | | |
+ | | | determined by this parameter. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+ | ``MBEDTLS_CONFIG_FILE`` | Configuration header | The Mbed Crypto library can be configured to support different | To be configured based on the | ``./platform/ext/common/tfm_mbedcrypto_config.h`` |
+ | | | algorithms through the usage of a a configuration header file | application and platform requirements. | |
+ | | | at build time. This allows for tailoring FLASH/RAM requirements| | |
+ | | | for different platforms and use cases. | | |
+ +-------------------------------+---------------------------+----------------------------------------------------------------+-----------------------------------------+----------------------------------------------------+
+
+References
+----------
+
+.. [1] ``mbed-crypto`` repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: \ https://github.com/ARMmbed/mbed-crypto
+
+.. [2] Uniform Signature prototypes: \ https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/
+
+
+--------------
+
+*Copyright (c) 2019, Arm Limited. All rights reserved.*