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:

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 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 for both library model and IPC model.

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

./docs/user_guides/services/tfm_crypto_integration_guide.rst

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

../../../_images/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 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.

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.

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.

./platform/ext/common/tfm_mbedcrypto_config.h

References

1

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

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