Reducing Mbed TLS memory and storage footprint
This page includes some of the optimizations that can help you reduce the RAM and ROM footprint of the Mbed TLS library. These are generic optimizations that do not require massive modifications to the code. This page discusses reductions of the compiled library (see Binary footprint) and reductions to the runtime memory (see Memory footprint).
All of the settings described on this page are available in
mbedtls_config.h, see How do I configure Mbed TLS.
If you need to reduce your memory footprint even more or have related questions, please submit a query in our support forum or open an issue in our GitHub repository. We welcome ideas you may have to further reduce the size in RAM or ROM storage. Please, let us know if you have suggestions for improvements.
The binary footprint is the size of the actual file on disk, in the ROM or the flash.
By default, Mbed TLS offers several compatibility options and frequently used functionalities. To reduce the footprint, adapt
mbedtls_config.h to disable the functions that you do not need.
The memory footprint is the size of the memory needed at runtime to store variables, contexts and other runtime information.
Multiple Precision Integers (MPIs)
Reducing the maximum size of MPIs
MBEDTLS_MPI_MAX_SIZE is set to 1024 bytes (8192 bits). If you know that you will not use larger MPIs, you can reduce
Reducing the MPI window size
mbedtls_mpi_exp_mod() uses a sliding window size (
MBEDTLS_MPI_WINDOW_SIZE) of up to 6. You can reduce this value down to 1, which reduces the memory used to the detriment of performance. This only has an effect if you use RSA, DHM or
Disabling unused ECP curves
Disabling large elliptic curves that you do not use in your application saves a lot of memory.
Reducing the maximum ECP bits
By default, the
MBEDTLS_ECP_MAX_BITS is set to
521 to support 521 bits elliptic curves. If you know that you will only use smaller curves, you can safely reduce this value. However, this only has a minimal effect on the memory used.
Reducing the ECP window size
By default, elliptic curve multiplications use a window size (
MBEDTLS_ECP_WINDOW_SIZE) of up to 6. You can reduce this value down to 2, which reduces the memory used to the detriment of performance. The larger the elliptic curves, the bigger the impact. See also How to tune ECC resource usage.
Disabling the ECP fixed point optimizations
If you disable the ECP fixed point optimizations (
MBEDTLS_ECP_FIXED_POINT_OPTIM), you lose some performance but use less memory. See also How to tune ECC resource usage.
Reducing the SSL frame buffer
By default, Mbed TLS uses a 16 KB frame buffer to hold data for incoming and outgoing frames. This is a TLS standard requirement. If you control both sides of a connection (server and client), you can reduce the maximum frame size to reduce the buffers needed to store the data. The size of this frame is determined by
MBEDTLS_SSL_MAX_CONTENT_LEN. You can safely reduce this to a more appropriate size (such as 2 KB) if:
Both sides support the
max_fragment_lengthSSL extension (allowing reduction to under 1 KB for the buffers).
You know the maximum size that will ever be sent in a single SSL/TLS frame (whether or not you control both sides of the connection).
Storing AES tables in ROM
By default, our AES implementation uses tables that are computed the first time AES is used and then stored in RAM. You can store them in ROM by enabling
MBEDTLS_AES_ROM_TABLES. This is a RAM-ROM trade-off.
Parsing X.509 certificates without copying the raw certificate data
The X.509 CRT parsing APIs
mbedtls_x509_crt_parse_der() create an internal copy of the raw certificate data passed to them. While this allows you to free or reuse the input buffer, it means the raw certificate data will be twice in memory at some point.
To avoid that, the following API can be used to set up an X.509 certificate structure without making a copy of the input buffer:
int mbedtls_x509_crt_parse_der_nocopy( mbedtls_x509_crt *chain, const unsigned char *buf, size_t buflen );
The only difference between
mbedtls_x509_crt_parse_der() is that the buffer passed to
mbedtls_x509_crt_parse_der_nocopy() holding the raw DER-encoded certificate must stay unmodified for the lifetime of the established
X.509 certificate context. See the documentation for more information.
Example: If your own certificate and/or the trusted CA certificates are hardcoded in ROM, you may use
mbedtls_x509_parse_der_nocopy() to create X.509 certificate contexts from them without an additional copy in RAM.
Removing a peer certificate after the handshake
By default, Mbed TLS saves a copy of the peer certificate for the lifetime of an SSL session and makes it available through the public API
mbedtls_ssl_get_peer_cert(). If the application does not need to inspect the peer certificate, disabling the compile-time option
MBEDTLS_SSL_KEEP_PEER_CERTIFICATE saves RAM as the SSL module will not keep a copy of the peer certificate after the handshake.
mbedtls_ssl_get_peer_cert() to obtain the peer certificate is still present, but always returns
If you need to inspect the peer certificate during or immediately after the handshake, you may still disable
MBEDTLS_SSL_KEEP_PEER_CERTIFICATE and inspect the certificate through a verification callback instead. A verification callback is a function called during the verification of the peer certificate chain and can be registered via
mbedtls_ssl_conf_verify(). For example, the test application
ssl_client2 uses a verification callback to provide a readable description of the peer certificate for debugging purposes. Also, you may use this callback to make a copy of the peer certificate, in case you want to manage it yourself.
We provide a few example configurations in the
configs directory. Two of them feature footprint optimization for a specific usage profile:
config-suite-b.his a minimal configuration supporting NSA Suite B.
config-ccm-psk-tls1_2.his a minimal configuration supporting pre-shared key and with AES-CCM.