Detailed Description

mbed TLS plugins (for AES, CCM, ECC, SHA) from SiliconLabs with hardware acceleration.

Introduction

The mbedtls/sl_crypto folder includes alternative implementations (plugins) from Silicon Labs for some of the mbed TLS library functions, including AES, CCM, CMAC, ECC (ECP, ECDH, ECDSA, ECJPAKE), SHA1 and SHA256. The plugins use the AES and CRYPTO hardware modules to accelerate the standard mbed TLS library functions that are implemented in C. The CRYPTO hardware module is incorporated in the new generations of MCUs from Silicon Labs and the AES hardware module is incorporated in the classic EFM32 MCUs from Silicon Labs.

Plugin Classes

There are two classes of CRYPTO Hardware Acceleration Plugins:

Class 1: Optimized for single threaded applications.
- sl_ecp.c
- sl_aes.c
- sl_sha1.c
- sl_sha256.c
Class 2: Plugins including CRYPTO preemption for multi-threaded application support.
- slcl_aes.c
- slcl_ccm.c
- slcl_cmac.c
- slcl_ecp.c
- slcl_sha1.c
- slcl_sha256.c

The plugins of class 1 do not support multi-threaded environments. I.e. the user application is responsible for not calling the mbed TLS interfaces using CRYPTO plugins with more than one thread concurrently. Class 1 plugins use less memory footprint (RAM and Flash) than class 2 plugins. Generally, class 1 plugins should be faster than class 2 plugins. Class 1 plugins only support device with the CRYPTO hardware module (EFR32, EFM32PG, etc.) Classic EFM32 devices with the AES hardware module are not supported.

Class 1 Plugins

sl_aes.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/aes.h' in order to accelerate the AES interface of mbed TLS on devices incorporating the CRYPTO module. See 'mbedtls/sl_crypto/include/aes_alt.h' for plugin specific definitions.

sl_ecp.c includes alternative implementations of some functions in the 'mbedtls/library/ecp.c' file in order to accelerate ECC point multiplication (the mbedtls_ecp_mul function) on 3 Short Weierstrass curves, namely secp192r1, secp224r1 and secp256r1. The api of ecp.c is unchanged defined in 'mbedtls/include/mbedtls/ecp.h' which is used by other ECC modules like 'mbedtls/include/mbedtls/ecdh.h', 'mbedtls/include/mbedtls/ecdsa.h' and 'mbedtls/include/mbedtls/ecjpake.h'.

sl_sha1.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/sha1.h' in order to accelerate SHA-1 interface of mbed TLS. See 'mbedtls/sl_crypto/include/sha1_alt.h' for plugin specific definitions.

sl_sha256.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/sha256.h' in order to accelerate SHA-256 interface of mbed TLS. See 'mbedtls/sl_crypto/include/sha256_alt.h' for plugin specific definitions.

Class 2 Plugins

The plugins in class 2 supports

multi-threaded applications by implementing CRYPTO preemption (CRYPTO Device Preemption)
yield CPU core when the CRYPTO device is busy (Yield When CRYPTO is Busy)
DMA to move data to/from CRYPTO registers (Alternative Data Transfer with DMA)

Please refer to Class 2 Plugins Initialization in order for details on how to enable and initialize the class 2 plugins.

Class 2 plugins (e.g. slcl_cmac.c) implement additional Silicon Labs specific APIs, which are not covered by the standard mbed TLS interface, including the standard error code interface. Therefore the plugins use a different bit layout for error code values called ecode which is defined in mbedtls_ecode.h.

slcl_aes.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/aes.h'. Classic EFM32s (EFM32GG, EFM32WG, etc.) with AES hardware module is supported, in addition to devices with the CRYPTO hardware module. See 'mbedtls/sl_crypto/include/aes_alt.h' for plugin specific definitions.

slcl_ccm.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/ccm.h'. Classic EFM32s (EFM32GG, EFM32WG, etc.) with AES hardware module is supported, in addition to devices with the CRYPTO hardware module. See 'mbedtls/sl_crypto/include/ccm_alt.h' for plugin specific definitions.

slcl_cmac.c implements functions to generate and verify CMAC authentication tags. The API is defined in 'mbedtls/sl_crypto/include/cmac_alt.h'.

slcl_ecp.c includes alternative implementations of some functions in the 'mbedtls/library/ecp.c' file in order to accelerate ECC point multiplication (specifically the mbedtls_ecp_mul function) on 3 Short Weierstrass curves, namely secp192r1, secp224r1 and secp256r1. The interface is defined in 'mbedtls/sl_crypto/include/ecp_alt.h' which is used by other ECC modules like 'mbedtls/include/mbedtls/ecdh.h', 'mbedtls/include/mbedtls/ecdsa.h' and 'mbedtls/include/mbedtls/ecjpake.h'.

slcl_sha1.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/sha1.h' in order to accelerate SHA-1 interface of mbed TLS. See 'mbedtls/sl_crypto/include/sha1_alt.h' for plugin specific definitions.

slcl_sha256.c includes alternative implementations of the functions defined in 'mbedtls/include/mbedtls/sha256.h' in order to accelerate SHA-256 interface of mbed TLS. See 'mbedtls/sl_crypto/include/sha256_alt.h' for plugin specific definitions.

Class 2 Plugins Initialization

Define MBEDTLS_SLCL_PLUGINS to enable class 2 plugins. The class 2 plugins use CRYPTO device context structures in order to manage the CRYPTO operations, one for each CRYPTO device. By default the device structures are initialized internally in order for backwards compatibility. However the internal initialization consumes some RAM because the device structures are instantiated statically inside the mbedTLS library. The user application may define MBEDTLS_DEVICE_INIT_INTERNAL_DISABLE in order to disable the internal device initialization, and take responsibility of allocating and initializing the device context structures itself. If MBEDTLS_DEVICE_INIT_INTERNAL_DISABLE is defined the user application is required to call mbedtls_device_init and mbedtls_device_set_instance before any other mbedTLS API calls in order to initialize the CRYPTO device context structure(s) (mbedtls_device_context) to be used in subsequent calls to the mbedTLS API. E.g. the code example below initializes all CRYPTO devices present, e.g. the single CRYPTO device on an EFR32MG1 or both CRYPTO device on an EFR32MG2:

  mbedtls_device_context mbedtls_device_ctx[MBEDTLS_DEVICE_COUNT];
  int device_instance;

  for (device_instance=0; device_instance<MBEDTLS_DEVICE_COUNT; device_instance++)
  {
    mbedtls_device_init(&mbedtls_device_ctx[device_instance]);
    mbedtls_device_set_instance(&mbedtls_device_ctx[device_instance],
                                device_instance);
  }

In subsequent calls to the mbedTLS API involving the SLCL plugins the user application can select which CRYPTO device to use by calling any of the mbedtls_xxx_set_device_instance functions associated with the particular SLCL plugin to use: E.g.

mbedtls_aes_set_device_instance
mbedtls_ccm_set_device_instance
mbedtls_cmac_set_device_instance
mbedtls_ecp_set_device_instance
mbedtls_sha1_set_device_instance
mbedtls_ahs256_set_device_instance

CRYPTO Device Preemption

The CRYPTO preemption support is enabled by compiling with MBEDTLS_CRYPTO_DEVICE_PREEMPTION defined. The CRYPTO preemption support allows a higher priority thread to preempt a lower priority thread that currently owns the CRYPTO module. The context (hardware state) of the lower priority thread will be saved and restored when the higher priority thread is done and releases the ownership of the CRYPTO hardware device.

When CRYPTO preemption is enabled the SLCL plugins implements critical regions in order to protect critical CRYPTO sequences from being preempted. The critical regions make use of a CRYPTO device lock object which is a mutex that supports priority inheritance in order to avoid deadlock situations from occurring. The device lock mutex is a member of the mbedtls_device_context structure and is initialized by the mbedtls_device_init function. The user application should carefully assign priorities to the different threads in the application.

CRYPTO preemption is internal functionality. The application is not directly exposed to preemption support. The user application threads can call into multiple mbedTLS APIs concurrently and the SLCL plugins will handle the preemption automatically. If there is a current thread owning the CRYPTO device when another challenging thread calls an mbedTLS API there will be an arbitration process. If the current owner is inside a critical region the challenger will need to wait until the owner exits the critial region. By default the challenger will not wait, and return an error code immediately. However the user application can specify the number of ticks to wait by calling the associated mbedtls_xxx_set_device_lock_wait_ticks function, e.g. mbedtls_ccm_set_device_lock_wait_ticks. When the current owner is not inside any critical regions the challenger will arbitrate for ownership. If the challenger has higher priority than the current owner, the challenger will preempt the current owner by storing the context and assume ownership.

The SLCL plugins requires a few services from the platform/OS mbedTLS is running on. The services are implemented in a OS abstraction layer called SLPAL which provides a common interface for the supported platforms/OSes. In the current version there are support for Micrium uC/OS-III, FreeRTOS and bare-metal (no OS).

Yield When CRYPTO is Busy

The slcl_ecp.c plugin accelerates ECC algorithms and needs some rather lengthy CRYPTO instruction sequences. The longest instruction sequences will consume more than 1000 clock cycles and in order to utilize these cycles the slcl_ecp.c plugin can yield the CPU core to other thread(s) while waiting for the CRYPTO hardware to complete the instruction sequence. This can be enabled by compiling with MBEDTLS_DEVICE_YIELD_WHEN_BUSY.

Alternative Data Transfer with DMA

The slcl_aes.c and slcl_ccm.c plugins support alernative mechanisms for moving data to/from CRYPTO registers. By default the CPU core will move data with load and store instructions. Alternatively the user application can select DMA to move data. The user application can select DMA I/O mode by calling the functions mbedtls_aes_set_device_io_mode and mbedtls_ccm_set_device_io_mode. MBEDTLS_INCLUDE_IO_MODE_DMA is required in order to use the DMA option.

Configuration

Please refer to Silicon Labs CRYPTO Hardware Acceleration Configuration for more information on configuration of plugins.

Collaboration diagram for Silicon Labs CRYPTO Hardware Acceleration Plugins:

Modules
	AES block cipher
	CRYPTO hardware accelerated AES block cipher.

	CBC-MAC (CCM) for 128-bit block ciphers
	CRYPTO hardware accelerated counter with CBC-MAC (CCM) for 128-bit block ciphers.

	CMAC cipher mode based on 128 bit AES
	CRYPTO hardware accelerated CMAC (Cipher-based Message Authentication Code)

	Elliptic curves over GF(p)
	CRYPTO hardware accelerated elliptic curves over GF(p).

	Portable timing interface
	Portable interface to the CPU cycle counter.

	SHA-1 cryptographic hash function
	CRYPTO hardware accelerated SHA-1 cryptographic hash function.

	SHA-224 and SHA-256 cryptographic hash function
	CRYPTO hardware accelerated SHA-224 and SHA-256 cryptographic hash function.