mbed TLS should build out-of-the box on a large variety of platforms. However, you may need to adjust a few platform-specific settings or want to customize the set of features that will be built. All of this is done in a single configuration file.

The configuration file

The default configuration file is located in include/mbedtls/config.h. It is fully documented and divided into sections:

  • System support is where you select options depending on your platform: does your compiler support inline assembly, does your libc/network stack provide IPv6, etc.
  • mbed TLS feature support is where you select which features will be enabled in the corresponding modules: which TLS version to support, which key exchanges, which specific elliptic curves, etc.
  • mbed TLS modules is where you select the modules to be built. Here you can, for example, totally disable RSA or MD5 if you don't need them.
  • Module configuration options is where you can set specific options for the each module, such as the maximum size of multi-precision integers, the size of the internal I/O buffers for SSL, etc. All of them have reasonable default values.

The configuration script

The configuration file can of course be edited manually with the text editor of your choice. In some cases however it may be useful to set options in a more programmatic way; we provide a Perl script scripts/config.pl for doing so. Usage is as follows:

scripts/config.pl unset <name>
scripts/config.pl set <name> [<value>]

When run this way, from mbed TLS's root directory, the config script automatically finds the config.h file. If you want to run it from another directory or on an other configuration file (see below), you'll need to use the -f option.

Alternative configuration files

Sometimes it is desirable to keep the custom configuration file for your application outside the mbed TLS source tree. This can be easily achieved by defining the macro MBEDTLS_CONFIG_FILE to the desired filename (including the quote or angular brackets) at compile time. For example, using make:

 CFLAGS="-Ipath/to/config -DMBEDTLS_CONFIG_FILE='<my_config.h>'" make

or, using Cmake (and clearing its cache first in case it's not the first run):

find . -iname '*cmake*' -not -name CMakeLists.txt -exec rm -rf {} +
CFLAGS="-Ipath/to/config -DMBEDTLS_CONFIG_FILE='<my_config.h>'" cmake .

We provide a file check_config.h which checks consistency of the configuration file. It is highly recommended to #include it at the end of your custom configuration file. When using the above setup, you may need to adapt the include directive depending on your compiler.

Example configurations

We provide example configurations in the configs directory. These are often minimal configurations for a specific goal, such as supporting the NSA suite B TLS profile. They also often include settings to reduce resource usage.

Did this help?