Using only a few modules from the library
Mbed TLS is a critical security component. While the developers do their best to avoid bugs and achieve the highest level of security, bugs can happen, including security-critical ones. As a consequence, if you make an application that includes code from Mbed TLS, you should be prepared to upgrade Mbed TLS.
You don’t have to use the whole library, however! Mbed TLS is designed so you can include only the modules that you need.
Making a minimal configuration
include/mbedtls/mbedtls_config.h contains a list of features and build-time options. To design a minimal configuration, start with a blank file and add the options you need. The documentation of each option describes its dependencies, if any.
Where to put your own configuration file? There are three choices:
You can edit the file in place, if you wish.
You can place a file called
mbedtls/mbedtls_config.hat some location in the include file search path that comes before the
includedirectory from the Mbed TLS source tree.
You can give your configuration file a different name and set the preprocessor symbol
MBEDTLS_CONFIG_FILEto the location of that file, including surrounding quotes.
For more information, see How to configure Mbed TLS.
Random generator example
For example, suppose you want a cryptographically secure random generator and nothing else. A random generator consists of two parts: an entropy source, and a pseudorandom generator seeded by the entropy source. Mbed TLS provides an interface to the system’s entropy sources in the
entropy module enabled by
MBEDTLS_ENTROPY_C. For the pseudorandom generator, there are two choices: CTR_DRBG or HMAC_DRBG, enabled with
The documentation of
MBEDTLS_ENTROPY_C states that it requires either
MBEDTLS_SHA256_C. The CTR_DRBG module requires
MBEDTLS_AES_C. The HMAC_DRBG module requires
MBEDTLS_MD_C, which in turn requires at least one hash module.
You decide to use HMAC_DRBG, and use SHA-512 as the hash function both for entropy and for the DRBG. As a consequence, you write the following configuration file:
#define MBEDTLS_ENTROPY_C #define MBEDTLS_HMAC_DRBG_C #define MBEDTLS_MD_C #define MBEDTLS_SHA512_C
Notes about Mbed TLS 2.x
In Mbed TLS 2.x, the configuration file is located at
You should add the following line at the end of your configuration file:
This will cause compilation errors with descriptive messages if the configuration is inconsistent.
Building Mbed TLS files directly in an application
Mbed TLS comes with build scripts for GNU make (
Makefile), CMake (
CMakeLists.txt) and Visual Studio (
visualc/VS2010/mbedTLS.sln). By default, these create static libraries
mbedtls which you can link into your application. (You don’t need to link
mbedtls if you don’t use these features.) For more information, see How to compile and build Mbed TLS.
If you prefer, you can include the Mbed TLS source files in your own build scripts. All the library code is in the
library subdirectory, except for a few features that use code from the
3rdparty directory tree. All the public headers are in the
include directory tree.
Compiling with Mbed TLS headers
Both when building your application and when building Mbed TLS source files, make sure that the
include directory of the Mbed TLS source tree is present in the header search path. For example, if Mbed TLS is in the subdirectory
$ cc -I external/mbedtls/include …
If you have a custom configuration file with the same name in a different directory, it must come first on the header search path. For example, if your Mbed TLS configuration file is located at
configs/mbedtls/mbedtls_config.h and the Mbed TLS source tree is located at
$ cc -I configs -I external/mbedtls/include …
Recall that alternatively, you can give your configuration file a different name and specify its location with the preprocessor symbol
MBEDTLS_CONFIG_FILE. For example, if your Mbed TLS configuration file is located at
my_mbedtls_config.h and the Mbed TLS source tree is located at
$ cc -DMBEDTLS_CONFIG_FILE='"my_mbedtls_config.h"' -I configs -I external/mbedtls/include …
Note that you must pass the same configuration when building Mbed TLS and building your application. Passing a different configuration is likely to result in misbehavior at runtime.