| Author: | Antonio de Angelis |
|---|---|
| Organization: | Arm Limited |
| Contact: | Antonio de Angelis <antonio.deangelis@arm.com> |
Table of Contents
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.
The TF-M Crypto service is implemented by a number of different software components, which are listed below:
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:
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.
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.
| 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. |
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 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 |
| [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.