15. Crypto Service design ¶

Author: Antonio de Angelis
Organization: Arm Limited
Contact: Antonio de Angelis <antonio.deangelis@arm.com>
Status: Accepted

Table of Contents

Crypto Service design

15.1. Abstract ¶

This document describes the design of the TF-M Cryptographic Secure Service (in short, TF-M Crypto service).

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.

15.3. Components ¶

The TF-M Crypto service is implemented by a number of different software components, which are listed below:

Components table¶
Component name	Description	Location
SPE client API interface	This module exports the client API of PSA Crypto to the other services available in TF-M.	`./secure_fw/partitions/crypto/tfm_crypto_secure_api.c`
NSPE client API interface	This module exports the client API of PSA Crypto to the NSPE (i.e. to the applications).	`./interface/src/tfm_crypto_api.c`
Mbed Crypto	The Mbed Crypto library is used in the service as a cryptographic library exposing the PSA Crypto API interface.	Needed as dependency at the same level of the TF-M folder, i.e. `../mbed-crypto`
Init module	This module handles the initialisation of the service objects 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.	`./secure_fw/partitions/crypto/crypto_init.c`
Alloc module	This module handles the allocation of contexts for multipart operations in the Secure world.	`./secure_fw/partitions/crypto/crypto_alloc.c`
Service modules	These modules (AEAD, Asymmetric, Cipher, Key Deriv, Hash, Key, MAC) represent a thin layer which is in charge of servicing the calls from the SPE/NSPE client API interfaces. They provide parameter sanitation and context retrieval for multipart operations, and dispatching to the corresponding library function exposed by Mbed Crypto for the desired functionality. All the functions in the Service modules are based on the Uniform Signature prototype 2 .	`./secure_fw/partitions/crypto/crypto_aead.c` `./secure_fw/partitions/crypto/crypto_asymmetric.c` `./secure_fw/partitions/crypto/crypto_cipher.c` `./secure_fw/partitions/crypto/crypto_key_derivation.c` `./secure_fw/partitions/crypto/crypto_hash.c` `./secure_fw/partitions/crypto/crypto_key.c` `./secure_fw/partitions/crypto/crypto_mac.c`
Manifest	The manifest file is a description of the service components for both library mode and IPC mode.	`./secure_fw/partitions/crypto/manifest.yaml`
CMake files and headers	The CMake files are used by the TF-M CMake build system to build the service as part of the Secure FW build. The service is built as a static library (`tfm_crypto.a`). The build system allows to build as well the Mbed Crypto library as part of the Secure FW build process and archive it with the static library of the Crypto service. 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__`.	`./secure_fw/partitions/crypto/CMakeLists.inc` `./secure_fw/partitions/crypto/CMakeLists.txt` `./interface/include/tfm_crypto_defs.h` `./secure_fw/partitions/crypto/tfm_crypto_api.h` `./secure_fw/partitions/crypto/tfm_crypto_signal.h` `./secure_fw/partitions/crypto/spe_crypto.h`
Documentation	The integration guide contains the description of the TF-M Crypto service modules and interfaces.	`./docs/user_guides/services/tfm_crypto_integration_guide.rst`

The interaction between the different components is described by the following block diagram:

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.

15.4. 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.

Init and Alloc modules APIs¶
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.

15.5. 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.

Configuration parameters table¶
Parameter	Type	Description	Scope	Default
`CRYPTO_ENGINE_BUF_SIZE`	CMake build configuration parameter	Buffer used by Mbed Crypto for its own allocations at runtime. This is a buffer allocated in static memory.	To be configured based on the desired use case and application requirements.	8096 (bytes)
`CRYPTO_CONC_OPER_NUM`	CMake build configuration parameter	This parameter defines the maximum number of possible concurrent operation contexts (cipher, MAC, hash and key deriv) for multi-part operations, that can be allocated simultaneously at any time.	To be configured based on the desire use case and platform requirements.	8
`CRYPTO_IOVEC_BUFFER_SIZE`	CMake build configuration parameter	This parameter applies only to IPC mode builds. In IPC mode, during a Service call, input and outputs are allocated temporarily in an internal scratch buffer whose size is determined by this parameter.	To be configured based on the desired use case and application requirements.	5120 (bytes)
`MBEDTLS_CONFIG_FILE`	Configuration header	The Mbed Crypto library can be configured to support different algorithms through the usage of a a configuration header file at build time. This allows for tailoring FLASH/RAM requirements for different platforms and use cases.	To be configured based on the application and platform requirements.	`./platform/ext/common/tfm_mbedcrypto_config.h`

15.6. 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(1,2,3): Uniform Signature prototypes: https://developer.trustedfirmware.org/w/tf_m/design/uniform_secure_service_signature/

15. Crypto Service design¶

15.1. Abstract¶

15.2. Introduction¶

15.3. Components¶

15.4. Service API description¶

15.5. Configuration parameters¶

15.6. References¶