Porting Mbed TLS to the STM32H5 platform with hardware crypto acceleration

STea · ‎2024-11-25

Summary

This article shows how to integrate Mbed TLS with hardware acceleration offloading benefiting from embedded hardware crypto engines (AES, PKA, HASH).

Introduction

The STM32H5 series is a powerful microcontroller family that benefits from hardware cryptographic acceleration. Integrating hardware support into the Mbed TLS wrapper can significantly enhance the performance of cryptographic operations. Below are the steps to achieve this integration based on the information provided in the context.

1. Prerequisites

Software:

STM32CubeIDE version 1.10.0 or newer
Mbed TLS library
Terminal emulator (we use Tera Term for this article)

Hardware:

STM32H573 Discovery kit

2. MbedTLS library cryptographic capabilities

MbedTLS offers an open-source implementation of cryptographic primitives, X.509 certificate handling, and the SSL/TLS and DTLS protocols. It includes a reference implementation of the PSA cryptography API and supports the PSA cryptoprocessor driver interface, allowing integration with cryptoprocessor drivers. Its small code footprint makes Mbed TLS ideal for embedded systems. The project is widely used, with notable users including TF-A, TF-M, and OP-TEE.

The STM32H5 uses Mbed TLS library in the context of ROT (root of trust project). Especially, in the boot process, where it checks for the authenticity and performs integrity checks of the project firmware and data images. The core function of this application relies on the mcuboot middleware and the mbed-crypto middleware (which is the same as Mbed TLS, see this GitHub link for more information.) It relies on cryptography hardware peripherals for optimal performances (PKA, SAE, HASH, RNG).

Hardware acceleration allows you to use alternative implementations of cryptographic primitives in most modules, leveraging hardware acceleration when available. This is done by defining the appropriate MBEDTLS_*_ALT preprocessor symbol for each module.
For instance, defining MBEDTLS_AES_ALT replaces the entire AES API with a hardware-accelerated AES driver, while MBEDTLS_AES_ENCRYPT_ALT replaces only the AES block encrypt functionality.

Mbed TLS is portable across different architectures and operating systems, thanks to its use of generic C and minimized platform dependencies. This ensures environment and architecture independence, reducing OS-dependent code and isolating platform-specific code from the portable core.

The library's modular design means that many modules operate independently of any runtime or environment.

3. Steps

In this section, we describe the steps needed to integrate MbedTLS and the alternate implementation files associated to be able to offload CPU calculation with hardware crypto engines. For this demonstration, we recover the MbedTLS library source code available from the attached MbedTLS_porting.zip.

Note: You can skip these steps and get the working example from the attached project as a template for your project (see attached MbedTLS_integration.zip).

Additionally, get ready to use the alternate implementation of AES SHA256 RSA from the ROT project in \STM32Cube_FW_H5_V1.2.0\Projects\STM32H573I-DK\Applications\ROT\OEMiROT_Boot\Src

You can find the files in the attached MbedTLS_porting.zip file.

Start a project from CubeMX in which we activate the crypto accelerator modules as well as the USART1 for logging purposes:

1. Activate the ICACHE.

2. Configure the clock.

3. Enable USART1 with pins PA9 and PA10 (mapped to Virtual Com Port) leaving other settings as-is.

4. Enable AES PKA RNG and HASH leaving the default configuration.

5. Generate the project.

You should have the following file system skeleton. We copy the folder containing the MbedTLS source code into our generated project as shown below. If you want the attached project to work, set the paths as illustrated bellow as they will be referred to later in the project settings.

6. Open the project in STM32CubeIDE and add the header and source files for the alternate implementation. Do this before opening the project by adding the files in the project's Src and Inc folders.

7. Add the include paths for MbedTLS header files to be recognized by your project.

8. In the project explorer, include the "Middlewares/MbedTLS/library" folder in the build and exclude the "Middlewares/MbedTLS/library/templates" from the build.

9. Add the necessary defines to take the alternate implementation files into consideration instead of the source file in the library with a software implementation this is done in the MbedTLS_config.h file (attached in the file below and integrated in the full project MbedTLS_integration.zip attached below).

10. Add the following calls below and include the "mbedtls.h" into your main.c file to make the requested header files of the MbedTLS library visible from main.c. To make sure that the lib is properly integrated, we run the selftests for the enabled crypto algorithms which benefit from hardware leveraging.

Note: Other calls to the software-implemented algorithms are still available and valid and can be used when Hardware acceleration is unavailable.

  int v = 1; /* v=1 for verbose mode */
  if( mbedtls_sha256_self_test(v)  == 0 )
   {
	  mbedtls_printf( "  Executed SHA256 test suites\n\n" );
   }
  if( mbedtls_aes_self_test(v)  == 0 )
   {
 	  mbedtls_printf( "  Executed AES test suites\n\n" );
   }
  if( mbedtls_gcm_self_test(v)  == 0 )
   {
 	  mbedtls_printf( "  Executed AES GCM test suites\n\n" );
   }
  if( mbedtls_rsa_self_test(v)  == 0 )
   {
	  mbedtls_printf( "  Executed RSA test suites\n\n" );
   }

11. Build and run. We should visualize via a terminal emulator like Tera Term that all selftests passed, indicating that the alternate implementation is working as expected.

Conclusion

Integrating Mbed TLS with hardware acceleration on the STM32H5 series microcontrollers significantly enhances the performance of cryptographic operations by leveraging embedded hardware crypto engines.

By incorporating the Mbed TLS library with alternate implementations, developers can offload CPU calculations to hardware crypto engines. This not only optimizes performance but also ensures the security and integrity of the system, particularly in applications like the Root of Trust (ROT) project.

The successful execution of self-tests for various cryptographic algorithms, as demonstrated, confirms the proper integration and functionality of the hardware-accelerated cryptographic operations.