Crypto Service Integration Guide

Introduction

TF-M Crypto service allows application to use cryptography primitives such as symmetric and asymmetric ciphers, hash, message authentication codes (MACs) and authenticated encryption with associated data (AEAD).

Code structure

The PSA interfaces for the Crypto service are located in interface/include. The only header to be included by applications that want to use functions from the PSA API is psa/crypto.h. The TF-M Crypto service source files are located in secure_fw/partitions/crypto.

PSA interfaces

The TF-M Crypto service exposes the PSA interfaces detailed in the header psa/crypto.h. This header, in turn, includes several other headers which are not meant to be included directly by user applications. For a detailed description of the PSA API interface, please refer to the comments in the psa/crypto.h header itself.

Service source files

  • crypto_cipher.c : This module handles requests for symmetric cipher operations

  • crypto_hash.c : This module handles requests for hashing operations

  • crypto_mac.c : This module handles requests for MAC operations

  • crypto_aead.c : This module handles requests for AEAD operations

  • crypto_key_derivation.c : This module handles requests for key derivation related operations

  • crypto_key_management.c : This module handles requests for key management related operations

  • crypto_key.c : This module handles requests for key backend operations, including key attributes switch between caller and service.

  • crypto_asymmetric.c : This module handles requests for asymmetric cryptographic operations

  • crypto_init.c : This module provides basic functions to initialise the secure service during TF-M boot. When the service is built for IPC model compatibility, this layer handles as well the connection requests and the proper dispatching of requests to the corresponding functions, and it holds the internal buffer used to allocate temporarily the IOVECs needed. The size of this buffer is controlled by the TFM_CRYPTO_IOVEC_BUFFER_SIZE define. This module also provides a static buffer which is used by the Mbed Crypto library for its own allocations. The size of this buffer is controlled by the TFM_CRYPTO_ENGINE_BUF_SIZE define

  • crypto_alloc.c : This module is required for the allocation and release of crypto operation contexts in the SPE. The TFM_CRYPTO_CONC_OPER_NUM, defined in this file, determines how many concurrent contexts are supported for multipart operations (8 for the current implementation). For multipart cipher/hash/MAC/generator operations, a context is associated to the handle provided during the setup phase, and is explicitly cleared only following a termination or an abort

  • tfm_crypto_secure_api.c : This module implements the PSA Crypto API client interface exposed to the Secure Processing Environment

  • tfm_crypto_api.c : This module is contained in interface/src and implements the PSA Crypto API client interface exposed to the Non-Secure Processing Environment.

  • tfm_mbedcrypto_alt.c : This module contains alternative implementations of Mbed Crypto functions. Decryption code is skipped in AES CCM mode in Profile Small by default.

Crypto Backend configuration

The Crypto service can use either a hardware crypto accelerator backend like CC-312 or a software crypto library which by default is MbedTLS.

If using MbedTLS as backend, then the library configuration is supplied using the TFM_MBEDCRYPTO_CONFIG_PATH and TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH cmake option.

Platforms can specify an extra config file by setting the TFM_MBEDCRYPTO_PLATFORM_EXTRA_CONFIG_PATH variable (which is a wrapper around the MBEDTLS_USER_CONFIG_FILE option). This is preferred for platform configuration over TFM_MBEDCRYPTO_CONFIG_PATH and TFM_MBEDCRYPTO_PSA_CRYPTO_CONFIG_PATH as it does not interfere with config changes due to TFM Profile.

Note

The default entropy source configured for MbedTLS is MBEDTLS_ENTROPY_NV_SEED with unique seed. For production devices, it can also select a hardware entropy source via MBEDTLS_ENTROPY_HARDWARE_ALT

Other Crypto Service Build Definitions

  • CRYPTO_STACK_SIZE- Defines the stack size of the Crypto Secure Partition. This value mainly depends on other crypto service configurations, the build type(debug, release and minisizerel) and compiler.

Crypto service integration

In this section, a brief description of the required flow of operation for the functionalities exported by the PSA Crypto interface is given, with particular focus on the TF-M Crypto service specific operations. For the details of the generic PSA Crypto interface operations, please refer directly to the header psa/crypto.h.

Most of the PSA Crypto multipart APIs require an operation context to be allocated by the application and then to be passed as a pointer during the following API calls. These operation contexts are of four main types described below:

  • psa_key_derivation_operation_t - Operation context for key derivation

  • psa_hash_operation_t - Operation context for multipart hash operations

  • psa_mac_operation_t - Operation context for multipart MAC operations

  • psa_cipher_operation_t - Operation context for multipart cipher operations

The user applications are not allowed to make any assumption about the original types behind these typedefs, which are defined inside psa/crypto.h. In the scope of the TF-M Crypto service, these types are regarded as handles to the corresponding implementation defined structures which are stored in the Secure world.


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