Mbed TLS glue layer

The Mbed TLS glue layer allows for using both the hardware-accelerated and software implementation of cryptography at the same time. A typical use case is if the cryptographic algorithm is limited in hardware support (for example, the AES key size or supported ciphers). In this case, the Mbed TLS glue layer enables a dynamic check to verify whether the cryptographic algorithm is supported in hardware. If it is not supported, the glue layer calls into a different enabled backend as a fallback.

The Mbed TLS glue layer is written by Nordic Semiconductor ASA and is a part of the nrf_security module. The Mbed TLS glue layer is dependent on Kconfig variables in the nRF Connect SDK build system.

Support and priority

To select the backend, the Mbed TLS glue layer implements a functionality check with priority reporting. The check is performed using a check function. This function is called from the API which provides configuration changes that determine the selection between the enabled backends.

Example: cc3xx backend AES CCM support and priority check
static int mbedtls_ccm_check(mbedtls_cipher_id_t cipher, unsigned int keybits) {
        return (keybits == 128) ? 3 : 0;
}

In this example, the AES CCM support in the backend will report priority level 3 if the key size is 128, or 0 if the key size is different. The Arm CryptoCell cc3xx backend does not support a larger key size. If the key size is larger than 128 bits, then another enabled backend is used.

Note

The check function can be called from multiple APIs in the Mbed TLS glue layer. An example of a location that determines backend selection is an API to set an encryption key, in which case the key size may change, demanding a new selection of available and prioritized backends.

Note

Hardware-accelerated cryptography through the Arm CryptoCell cc3xx backend is prioritized if it is supported.

Enabling the Mbed TLS glue layer

The Mbed TLS glue layer is automatically enabled when two backends are enabled for one or more of the following groups of algorithms:

  • AES (ECB, CBC, CTR, and CCM/CCM*)

  • CMAC

  • DHM

Mbed TLS glue layer mechanisms

The Mbed TLS glue layer relies on symbol renaming of known APIs in Mbed TLS to prevent collisions of identically named functions in multiple backends. The backend implementation is reached using a table of function pointers corresponding to the renamed symbols.

Example: cc3xx backend ECDH function table
const mbedtls_ecdh_funcs mbedtls_ecdh_cc3xx_backend_funcs = {
        .check = mbedtls_ecdh_check,
        .gen_public = mbedtls_ecdh_gen_public,
        .compute_shared = mbedtls_ecdh_compute_shared,
};

mbedtls_ecdh_cc3xx_backend_funcs() points to Mbed TLS APIs in nrf_cc3xx_mbedcrypto library which is renamed if Mbed TLS glue layer is enabled. The function pointers gen_public and compute_shared have signatures equal to the corresponding Mbed TLS APIs.

The complete list of APIs that can be renamed in the Mbed TLS glue layer can be found in nrfxlib/nrf_security/src/mbedcrypto_glue/symbol_rename.template.txt