Alternative ways of allocating memory in Mbed TLS

In several situations, like when not having an operating system on an embedded platform, there is no real availability of a heap or calloc()/free(). Mbed TLS still needs some form of dynamic memory allocation to operate the SSL stack. We could just assume the maximum sizes for all structures, but that would consume a lot of memory space. Instead we opted for letting Mbed TLS only use hooks to allocate and free dynamic memory.

This currently gives you two options:

  1. Provide your own allocation and freeing functions.

  2. Use the buffer allocator feature in Mbed TLS.

To enable the memory allocation layer, define MBEDTLS_PLATFORM_C and MBEDTLS_PLATFORM_MEMORY in the mbedtls_config.h file. See How do I configure Mbed TLS.

If you do not enable the layer, the libc standard calloc() and free() are used.


Internally, there are just two function pointers mbedtls_calloc() and mbedtls_free() that are called within Mbed TLS for each dynamic memory allocation or de-allocation.

extern void * (*mbedtls_calloc)( size_t n, size_t size );
extern void (*mbedtls_free)( void *ptr );

The prototypes for these functions are identical to the libc standard calloc() and free(). Without any further calls, the default libc names are assigned to these pointers.

No libc equivalents

If your system does not have a libc equivalent, you will get compile errors as calloc() or free() cannot be found.

Defining MBEDTLS_PLATFORM_NO_STD_FUNCTIONS in the mbedtls_config.h file prevents Mbed TLS from ever knowing about those functions.

Providing your own hooks

If your operating system already provides an alternative to the libc allocator functions, you can set them with:

int mbedtls_platform_set_calloc_free( void * (*calloc_func)( size_t, size_t ),
                                      void (*free_func)( void * ) );

Using the Mbed TLS buffer allocator

If you want Mbed TLS to allocate everything inside a static buffer, you can enable the buffer allocator by defining MBEDTLS_MEMORY_BUFFER_ALLOC_C in the mbedtls_config.h file.

Before calling any other Mbed TLS functions, enable the buffer allocator as follows:

unsigned char memory_buf[100000];
mbedtls_memory_buffer_alloc_init( memory_buf, sizeof(memory_buf) );

Security warning

The buffer allocator is a straightforward approach to a dynamic memory allocator. No special heap protection mechanisms have been implemented.

Using the buffer allocator elsewhere

The buffer allocator itself has no internal dependencies on any of the rest of Mbed TLS. So you can use it within your own codebase as well.