Crypto Service design

Author:

Antonio de Angelis

Organization:

Arm Limited

Contact:

Antonio de Angelis <antonio.deangelis@arm.com>

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 44 Components table

Component name	Description	Location
Client API interface	This module exports the client API of PSA Crypto to the users.	./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 model. 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.	./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 ‘’./secure_fw/partitions/crypto/crypto_key_management.c’’
Manifest	The manifest file is a description of the service components.	./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 model. 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.	./user_guides/services/tfm_crypto_integration_guide.rst

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

Fig. 12 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 model, 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) 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 45 Init and Alloc modules APIs

Function	Module	Caller	Scope
tfm_crypto_init()	Init	SPM	Called during TF-M boot for initialisation. In IPC model, 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 46 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 model builds. In IPC model, 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.	./lib/ext/mbedcrypto/mbedcrypto_config/tfm_mbedcrypto_config_default.h
MBEDTLS_PSA_CRYPTO_CONFIG_FILE	Configuration header	This header file specifies which cryptographic mechanisms are available through the PSA API when #MBEDTLS_PSA_CRYPTO_CONFIG is enabled, and is not used when #MBEDTLS_PSA_CRYPTO_CONFIG is disabled.	To be configured based on the application and platform requirements.	./lib/ext/mbedcrypto/mbedcrypto_config/crypto_config_default.h

References

[1]

mbed-crypto repository which holds the PSA Crypto API specification and the Mbed Crypto reference implementation: https://github.com/Mbed-TLS

---

Copyright (c) 2019-2022, Arm Limited. All rights reserved.