mbed TLS supports alternative implementation for most of its cryptography modules. A common use case is for hardware accelerated cryptography engines. There are a couple of methods for alternative implementations: specific function replacement and full module replacement. The latter is the more common one.

The configuration file contains the cryptography modules, which you can replace with alternative implementation. These are named MBEDTLS_<MODULE NAME>_ALT. In order to support alternative implementation for a module, uncomment the corresponding *_ALT definition. Function replacement is according to the function name, with the suffix of _ALT. To support hardware entropy source, enable MBEDTLS_ENTROPY_HARDWARE_ALT in the configuration file.

Note: For ECP function replacement, the behavior is different. Refer to the ECP module for more information.


There are few basic rules for supporting full module alternative implementation:
1. Enable the relevant *_ALT in the configuration file.
1. Define the module context in <module name>_alt.h file.
1. Implement the module API in <module name>_alt.c file.
1. If the hardware doesn't support specific functionality, such as key size, then the developer must decide whether to implement a SW fallback or return an error.

  • For "function alternative implementation" method, implement the alternative function in any file that is being compiled as part of the library.
  • For hardware entropy implementation, implement mbedtls_hardware_poll() in any file that is being compiled as part of the library.

AES example - full module replacement

In config.h:

  • enable MBEDTLS_AES_ALT definition.

Define aes_alt.h:

  • define mbedtls_aes_context that will fit the platform's needs.
  • define the platform specific functions that will be used by the alternative implementation.

Define aes_alt.c:

  • write an alternative implementation of the AES interface, as defined in aes.h, which will access the platform's hardware accelerated engine.

MD5 example - MD5 process function replacement

In config.h:

  • enable MBEDTLS_MD5_PROCESS_ALT definition.

Define md5_alt.c:

  • implement mbedtls_md5_process.

Did this help?