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:
Component name |
Description |
Location |
---|---|---|
Client API interface |
This module exports the client API of PSA Crypto to the users. |
|
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. |
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. |
|
Alloc module |
This module handles the allocation of contexts for multipart operations in the Secure world. |
|
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. |
|
Manifest |
The manifest file is a description of the service components. |
|
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 ( |
|
Documentation |
The integration guide contains the description of the TF-M Crypto service modules and interfaces. |
|
The interaction between the different components is described by the following block diagram:
![../../_images/tfm_crypto_design.png](../../_images/tfm_crypto_design.png)
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.
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.
Parameter |
Type |
Description |
Scope |
Default |
---|---|---|---|---|
|
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) |
|
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 |
|
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) |
|
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. |
|
|
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. |
|
References
Copyright (c) 2019-2022, Arm Limited. All rights reserved.