File config.h

Configuration options (set of defines)

This set of compile-time options may be used to enable or disable features selectively, and reduce the global memory footprint.

SECTION: System support

This section sets system specific settings.

MBEDTLS_HAVE_ASM

The compiler has support for asm().

Requires support for asm() in compiler.

Used in: library/aria.c library/timing.c include/mbedtls/bn_mul.h

Required by: MBEDTLS_AESNI_C (on some platforms) MBEDTLS_PADLOCK_C

Comment to disable the use of assembly code.

MBEDTLS_NO_UDBL_DIVISION

The platform lacks support for double-width integer division (64-bit division on a 32-bit platform, 128-bit division on a 64-bit platform).

Used in: include/mbedtls/bignum.h library/bignum.c

The bignum code uses double-width division to speed up some operations. Double-width division is often implemented in software that needs to be linked with the program. The presence of a double-width integer type is usually detected automatically through preprocessor macros, but the automatic detection cannot know whether the code needs to and can be linked with an implementation of division for that type. By default division is assumed to be usable if the type is present. Uncomment this option to prevent the use of double-width division.

Note that division for the native integer type is always required. Furthermore, a 64-bit type is always required even on a 32-bit platform, but it need not support multiplication or division. In some cases it is also desirable to disable some double-width operations. For example, if double-width division is implemented in software, disabling it can reduce code size in some embedded targets.

MBEDTLS_NO_64BIT_MULTIPLICATION

The platform lacks support for 32x32 -> 64-bit multiplication.

Used in: library/poly1305.c

Some parts of the library may use multiplication of two unsigned 32-bit operands with a 64-bit result in order to speed up computations. On some platforms, this is not available in hardware and has to be implemented in software, usually in a library provided by the toolchain.

Sometimes it is not desirable to have to link to that library. This option removes the dependency of that library on platforms that lack a hardware 64-bit multiplier by embedding a software implementation in Mbed TLS.

Note that depending on the compiler, this may decrease performance compared to using the library function provided by the toolchain.

MBEDTLS_HAVE_SSE2

CPU supports SSE2 instruction set.

Uncomment if the CPU supports SSE2 (IA-32 specific).

MBEDTLS_HAVE_TIME

System has time.h and time(). The time does not need to be correct, only time differences are used, by contrast with MBEDTLS_HAVE_TIME_DATE

Defining MBEDTLS_HAVE_TIME allows you to specify MBEDTLS_PLATFORM_TIME_ALT, MBEDTLS_PLATFORM_TIME_MACRO, MBEDTLS_PLATFORM_TIME_TYPE_MACRO and MBEDTLS_PLATFORM_STD_TIME.

Comment if your system does not support time functions.

Note

If MBEDTLS_TIMING_C is set - to enable the semi-portable timing interface - timing.c will include time.h on suitable platforms regardless of the setting of MBEDTLS_HAVE_TIME, unless MBEDTLS_TIMING_ALT is used. See timing.c for more information.

MBEDTLS_HAVE_TIME_DATE

System has time.h, time(), and an implementation for mbedtls_platform_gmtime_r() (see below). The time needs to be correct (not necessarily very accurate, but at least the date should be correct). This is used to verify the validity period of X.509 certificates.

Comment if your system does not have a correct clock.

Note

mbedtls_platform_gmtime_r() is an abstraction in platform_util.h that behaves similarly to the gmtime_r() function from the C standard. Refer to the documentation for mbedtls_platform_gmtime_r() for more information.

Note

It is possible to configure an implementation for mbedtls_platform_gmtime_r() at compile-time by using the macro MBEDTLS_PLATFORM_GMTIME_R_ALT.

MBEDTLS_PLATFORM_MEMORY

Enable the memory allocation layer.

By default Mbed TLS uses the system-provided calloc() and free(). This allows different allocators (self-implemented or provided) to be provided to the platform abstraction layer.

Enabling MBEDTLS_PLATFORM_MEMORY without the MBEDTLS_PLATFORM_{FREE,CALLOC}_MACROs will provide “mbedtls_platform_set_calloc_free()” allowing you to set an alternative calloc() and free() function pointer at runtime.

Enabling MBEDTLS_PLATFORM_MEMORY and specifying MBEDTLS_PLATFORM_{CALLOC,FREE}_MACROs will allow you to specify the alternate function at compile time.

An overview of how the value of mbedtls_calloc is determined:

• if !MBEDTLS_PLATFORM_MEMORY

  • mbedtls_calloc = calloc

• if MBEDTLS_PLATFORM_MEMORY

  • if (MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):

    • mbedtls_calloc = MBEDTLS_PLATFORM_CALLOC_MACRO

  • if !(MBEDTLS_PLATFORM_CALLOC_MACRO && MBEDTLS_PLATFORM_FREE_MACRO):

    • Dynamic setup via mbedtls_platform_set_calloc_free is now possible with a default value MBEDTLS_PLATFORM_STD_CALLOC.

    • How is MBEDTLS_PLATFORM_STD_CALLOC handled?

    • if MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:

      • MBEDTLS_PLATFORM_STD_CALLOC is not set to anything;

      • MBEDTLS_PLATFORM_STD_MEM_HDR can be included if present;

    • if !MBEDTLS_PLATFORM_NO_STD_FUNCTIONS:

      • if MBEDTLS_PLATFORM_STD_CALLOC is present:

        • User-defined MBEDTLS_PLATFORM_STD_CALLOC is respected;

      • if !MBEDTLS_PLATFORM_STD_CALLOC:

        • MBEDTLS_PLATFORM_STD_CALLOC = calloc

    • At this point the presence of MBEDTLS_PLATFORM_STD_CALLOC is checked.

    • if !MBEDTLS_PLATFORM_STD_CALLOC

      • MBEDTLS_PLATFORM_STD_CALLOC = uninitialized_calloc

    • mbedtls_calloc = MBEDTLS_PLATFORM_STD_CALLOC.

Defining MBEDTLS_PLATFORM_CALLOC_MACRO and MBEDTLS_PLATFORM_STD_CALLOC at the same time is not possible. MBEDTLS_PLATFORM_CALLOC_MACRO and MBEDTLS_PLATFORM_FREE_MACRO must both be defined or undefined at the same time. MBEDTLS_PLATFORM_STD_CALLOC and MBEDTLS_PLATFORM_STD_FREE do not have to be defined at the same time, as, if they are used, dynamic setup of these functions is possible. See the tree above to see how are they handled in all cases. An uninitialized MBEDTLS_PLATFORM_STD_CALLOC always fails, returning a null pointer. An uninitialized MBEDTLS_PLATFORM_STD_FREE does not do anything.

Requires: MBEDTLS_PLATFORM_C

Enable this layer to allow use of alternative memory allocators.

MBEDTLS_PLATFORM_NO_STD_FUNCTIONS

Do not assign standard functions in the platform layer (e.g. calloc() to MBEDTLS_PLATFORM_STD_CALLOC and printf() to MBEDTLS_PLATFORM_STD_PRINTF)

This makes sure there are no linking errors on platforms that do not support these functions. You will HAVE to provide alternatives, either at runtime via the platform_set_xxx() functions or at compile time by setting the MBEDTLS_PLATFORM_STD_XXX defines, or enabling a MBEDTLS_PLATFORM_XXX_MACRO.

Requires: MBEDTLS_PLATFORM_C

Uncomment to prevent default assignment of standard functions in the platform layer.

MBEDTLS_PLATFORM_EXIT_ALT

MBEDTLS_PLATFORM_XXX_ALT: Uncomment a macro to let Mbed TLS support the function in the platform abstraction layer.

Example: In case you uncomment MBEDTLS_PLATFORM_PRINTF_ALT, Mbed TLS will provide a function “mbedtls_platform_set_printf()” that allows you to set an alternative printf function pointer.

All these define require MBEDTLS_PLATFORM_C to be defined!

Requires: MBEDTLS_PLATFORM_TIME_ALT requires MBEDTLS_HAVE_TIME

Uncomment a macro to enable alternate implementation of specific base platform function

Note

MBEDTLS_PLATFORM_SNPRINTF_ALT is required on Windows; it will be enabled automatically by check_config.h

Warning

MBEDTLS_PLATFORM_XXX_ALT cannot be defined at the same time as MBEDTLS_PLATFORM_XXX_MACRO!

MBEDTLS_PLATFORM_TIME_ALT

MBEDTLS_PLATFORM_FPRINTF_ALT

MBEDTLS_PLATFORM_PRINTF_ALT

MBEDTLS_PLATFORM_SNPRINTF_ALT

MBEDTLS_PLATFORM_VSNPRINTF_ALT

MBEDTLS_PLATFORM_NV_SEED_ALT

MBEDTLS_PLATFORM_SETUP_TEARDOWN_ALT

MBEDTLS_PLATFORM_GMTIME_R_ALT

Uncomment the macro to let Mbed TLS use your alternate implementation of mbedtls_platform_gmtime_r(). This replaces the default implementation in platform_util.c.

gmtime() is not a thread-safe function as defined in the C standard. The library will try to use safer implementations of this function, such as gmtime_r() when available. However, if Mbed TLS cannot identify the target system, the implementation of mbedtls_platform_gmtime_r() will default to using the standard gmtime(). In this case, calls from the library to gmtime() will be guarded by the global mutex mbedtls_threading_gmtime_mutex if MBEDTLS_THREADING_C is enabled. We recommend that calls from outside the library are also guarded with this mutex to avoid race conditions. However, if the macro MBEDTLS_PLATFORM_GMTIME_R_ALT is defined, Mbed TLS will unconditionally use the implementation for mbedtls_platform_gmtime_r() supplied at compile time.

MBEDTLS_PLATFORM_ZEROIZE_ALT

Uncomment the macro to let Mbed TLS use your alternate implementation of mbedtls_platform_zeroize(). This replaces the default implementation in platform_util.c.

mbedtls_platform_zeroize() is a widely used function across the library to zero a block of memory. The implementation is expected to be secure in the sense that it has been written to prevent the compiler from removing calls to mbedtls_platform_zeroize() as part of redundant code elimination optimizations. However, it is difficult to guarantee that calls to mbedtls_platform_zeroize() will not be optimized by the compiler as older versions of the C language standards do not provide a secure implementation of memset(). Therefore, MBEDTLS_PLATFORM_ZEROIZE_ALT enables users to configure their own implementation of mbedtls_platform_zeroize(), for example by using directives specific to their compiler, features from newer C standards (e.g using memset_s() in C11) or calling a secure memset() from their system (e.g explicit_bzero() in BSD).

MBEDTLS_DEPRECATED_WARNING

Mark deprecated functions and features so that they generate a warning if used. Functionality deprecated in one version will usually be removed in the next version. You can enable this to help you prepare the transition to a new major version by making sure your code is not using this functionality.

This only works with GCC and Clang. With other compilers, you may want to use MBEDTLS_DEPRECATED_REMOVED

Uncomment to get warnings on using deprecated functions and features.

MBEDTLS_DEPRECATED_REMOVED

Remove deprecated functions and features so that they generate an error if used. Functionality deprecated in one version will usually be removed in the next version. You can enable this to help you prepare the transition to a new major version by making sure your code is not using this functionality.

Uncomment to get errors on using deprecated functions and features.

MBEDTLS_CHECK_PARAMS

This configuration option controls whether the library validates more of the parameters passed to it.

When this flag is not defined, the library only attempts to validate an input parameter if: (1) they may come from the outside world (such as the network, the filesystem, etc.) or (2) not validating them could result in internal memory errors such as overflowing a buffer controlled by the library. On the other hand, it doesn’t attempt to validate parameters whose values are fully controlled by the application (such as pointers).

When this flag is defined, the library additionally attempts to validate parameters that are fully controlled by the application, and should always be valid if the application code is fully correct and trusted.

For example, when a function accepts as input a pointer to a buffer that may contain untrusted data, and its documentation mentions that this pointer must not be NULL:

• The pointer is checked to be non-NULL only if this option is enabled.

• The content of the buffer is always validated.

When this flag is defined, if a library function receives a parameter that is invalid:

1. The function will invoke the macro MBEDTLS_PARAM_FAILED().

2. If MBEDTLS_PARAM_FAILED() did not terminate the program, the function will immediately return. If the function returns an Mbed TLS error code, the error code in this case is MBEDTLS_ERR_xxx_BAD_INPUT_DATA.

When defining this flag, you also need to arrange a definition for MBEDTLS_PARAM_FAILED(). You can do this by any of the following methods:

• By default, the library defines MBEDTLS_PARAM_FAILED() to call a function mbedtls_param_failed(), but the library does not define this function. If you do not make any other arrangements, you must provide the function mbedtls_param_failed() in your application. See platform_util.h for its prototype.

• If you enable the macro MBEDTLS_CHECK_PARAMS_ASSERT, then the library defines MBEDTLS_PARAM_FAILED(cond) to be assert(cond). You can still supply an alternative definition of MBEDTLS_PARAM_FAILED(), which may call assert.

• If you define a macro MBEDTLS_PARAM_FAILED() before including config.h or you uncomment the definition of MBEDTLS_PARAM_FAILED() in config.h, the library will call the macro that you defined and will not supply its own version. Note that if MBEDTLS_PARAM_FAILED() calls assert, you need to enable MBEDTLS_CHECK_PARAMS_ASSERT so that library source files include <assert.h>.

Uncomment to enable validation of application-controlled parameters.

MBEDTLS_CHECK_PARAMS_ASSERT

Allow MBEDTLS_PARAM_FAILED() to call assert, and make it default to assert. This macro is only used if MBEDTLS_CHECK_PARAMS is defined.

If this macro is not defined, then MBEDTLS_PARAM_FAILED() defaults to calling a function mbedtls_param_failed(). See the documentation of MBEDTLS_CHECK_PARAMS for details.

Uncomment to allow MBEDTLS_PARAM_FAILED() to call assert.

SECTION: Mbed TLS feature support

This section sets support for features that are or are not needed within the modules that are enabled.

MBEDTLS_TIMING_ALT

Uncomment to provide your own alternate implementation for mbedtls_timing_hardclock(), mbedtls_timing_get_timer(), mbedtls_set_alarm(), mbedtls_set/get_delay()

Only works if you have MBEDTLS_TIMING_C enabled.

You will need to provide a header “timing_alt.h” and an implementation at compile time.

MBEDTLS_AES_ALT

MBEDTLS__MODULE_NAME__ALT: Uncomment a macro to let Mbed TLS use your alternate core implementation of a symmetric crypto, an arithmetic or hash module (e.g. platform specific assembly optimized implementations). Keep in mind that the function prototypes should remain the same.

This replaces the whole module. If you only want to replace one of the functions, use one of the MBEDTLS__FUNCTION_NAME__ALT flags.

Example: In case you uncomment MBEDTLS_AES_ALT, Mbed TLS will no longer provide the “struct mbedtls_aes_context” definition and omit the base function declarations and implementations. “aes_alt.h” will be included from “aes.h” to include the new function definitions.

Uncomment a macro to enable alternate implementation of the corresponding module.

Warning

MD2, MD4, MD5, ARC4, DES and SHA-1 are considered weak and their use constitutes a security risk. If possible, we recommend avoiding dependencies on them, and considering stronger message digests and ciphers instead.

MBEDTLS_ARC4_ALT

MBEDTLS_ARIA_ALT

MBEDTLS_BLOWFISH_ALT

MBEDTLS_CAMELLIA_ALT

MBEDTLS_CCM_ALT

MBEDTLS_CHACHA20_ALT

MBEDTLS_CHACHAPOLY_ALT

MBEDTLS_CMAC_ALT

MBEDTLS_DES_ALT

MBEDTLS_DHM_ALT

MBEDTLS_ECJPAKE_ALT

MBEDTLS_GCM_ALT

MBEDTLS_NIST_KW_ALT

MBEDTLS_MD2_ALT

MBEDTLS_MD4_ALT

MBEDTLS_MD5_ALT

MBEDTLS_POLY1305_ALT

MBEDTLS_RIPEMD160_ALT

MBEDTLS_RSA_ALT

MBEDTLS_SHA1_ALT

MBEDTLS_SHA256_ALT

MBEDTLS_SHA512_ALT

MBEDTLS_XTEA_ALT

MBEDTLS_ECP_ALT

MBEDTLS_MD2_PROCESS_ALT

MBEDTLS__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use you alternate core implementation of symmetric crypto or hash function. Keep in mind that function prototypes should remain the same.

This replaces only one function. The header file from Mbed TLS is still used, in contrast to the MBEDTLS__MODULE_NAME__ALT flags.

Example: In case you uncomment MBEDTLS_SHA256_PROCESS_ALT, Mbed TLS will no longer provide the mbedtls_sha1_process() function, but it will still provide the other function (using your mbedtls_sha1_process() function) and the definition of mbedtls_sha1_context, so your implementation of mbedtls_sha1_process must be compatible with this definition.

Uncomment a macro to enable alternate implementation of the corresponding function.

Note

Because of a signature change, the core AES encryption and decryption routines are currently named mbedtls_aes_internal_encrypt and mbedtls_aes_internal_decrypt, respectively. When setting up alternative implementations, these functions should be overridden, but the wrapper functions mbedtls_aes_decrypt and mbedtls_aes_encrypt must stay untouched.

Note

If you use the AES_xxx_ALT macros, then it is recommended to also set MBEDTLS_AES_ROM_TABLES in order to help the linker garbage-collect the AES tables.

Warning

MD2, MD4, MD5, DES and SHA-1 are considered weak and their use constitutes a security risk. If possible, we recommend avoiding dependencies on them, and considering stronger message digests and ciphers instead.

Warning

If both MBEDTLS_ECDSA_SIGN_ALT and MBEDTLS_ECDSA_DETERMINISTIC are enabled, then the deterministic ECDH signature functions pass the the static HMAC-DRBG as RNG to mbedtls_ecdsa_sign(). Therefore alternative implementations should use the RNG only for generating the ephemeral key and nothing else. If this is not possible, then MBEDTLS_ECDSA_DETERMINISTIC should be disabled and an alternative implementation should be provided for mbedtls_ecdsa_sign_det_ext() (and for mbedtls_ecdsa_sign_det() too if backward compatibility is desirable).

MBEDTLS_MD4_PROCESS_ALT

MBEDTLS_MD5_PROCESS_ALT

MBEDTLS_RIPEMD160_PROCESS_ALT

MBEDTLS_SHA1_PROCESS_ALT

MBEDTLS_SHA256_PROCESS_ALT

MBEDTLS_SHA512_PROCESS_ALT

MBEDTLS_DES_SETKEY_ALT

MBEDTLS_DES_CRYPT_ECB_ALT

MBEDTLS_DES3_CRYPT_ECB_ALT

MBEDTLS_AES_SETKEY_ENC_ALT

MBEDTLS_AES_SETKEY_DEC_ALT

MBEDTLS_AES_ENCRYPT_ALT

MBEDTLS_AES_DECRYPT_ALT

MBEDTLS_ECDH_GEN_PUBLIC_ALT

MBEDTLS_ECDH_COMPUTE_SHARED_ALT

MBEDTLS_ECDSA_VERIFY_ALT

MBEDTLS_ECDSA_SIGN_ALT

MBEDTLS_ECDSA_GENKEY_ALT

MBEDTLS_ECP_INTERNAL_ALT

Expose a part of the internal interface of the Elliptic Curve Point module.

MBEDTLS_ECP__FUNCTION_NAME__ALT: Uncomment a macro to let Mbed TLS use your alternative core implementation of elliptic curve arithmetic. Keep in mind that function prototypes should remain the same.

This partially replaces one function. The header file from Mbed TLS is still used, in contrast to the MBEDTLS_ECP_ALT flag. The original implementation is still present and it is used for group structures not supported by the alternative.

The original implementation can in addition be removed by setting the MBEDTLS_ECP_NO_FALLBACK option, in which case any function for which the corresponding MBEDTLS_ECP__FUNCTION_NAME__ALT macro is defined will not be able to fallback to curves not supported by the alternative implementation.

Any of these options become available by defining MBEDTLS_ECP_INTERNAL_ALT and implementing the following functions: unsigned char mbedtls_internal_ecp_grp_capable( const mbedtls_ecp_group *grp ) int mbedtls_internal_ecp_init( const mbedtls_ecp_group *grp ) void mbedtls_internal_ecp_free( const mbedtls_ecp_group *grp ) The mbedtls_internal_ecp_grp_capable function should return 1 if the replacement functions implement arithmetic for the given group and 0 otherwise. The functions mbedtls_internal_ecp_init and mbedtls_internal_ecp_free are called before and after each point operation and provide an opportunity to implement optimized set up and tear down instructions.

Example: In case you set MBEDTLS_ECP_INTERNAL_ALT and MBEDTLS_ECP_DOUBLE_JAC_ALT, Mbed TLS will still provide the ecp_double_jac() function, but will use your mbedtls_internal_ecp_double_jac() if the group for the operation is supported by your implementation (i.e. your mbedtls_internal_ecp_grp_capable() function returns 1 for this group). If the group is not supported by your implementation, then the original Mbed TLS implementation of ecp_double_jac() is used instead, unless this fallback behaviour is disabled by setting MBEDTLS_ECP_NO_FALLBACK (in which case ecp_double_jac() will return MBEDTLS_ERR_ECP_FEATURE_UNAVAILABLE).

The function prototypes and the definition of mbedtls_ecp_group and mbedtls_ecp_point will not change based on MBEDTLS_ECP_INTERNAL_ALT, so your implementation of mbedtls_internal_ecp__function_name__ must be compatible with their definitions.

Uncomment a macro to enable alternate implementation of the corresponding function.

MBEDTLS_ECP_NO_FALLBACK

MBEDTLS_ECP_RANDOMIZE_JAC_ALT

MBEDTLS_ECP_ADD_MIXED_ALT

MBEDTLS_ECP_DOUBLE_JAC_ALT

MBEDTLS_ECP_NORMALIZE_JAC_MANY_ALT

MBEDTLS_ECP_NORMALIZE_JAC_ALT

MBEDTLS_ECP_DOUBLE_ADD_MXZ_ALT

MBEDTLS_ECP_RANDOMIZE_MXZ_ALT

MBEDTLS_ECP_NORMALIZE_MXZ_ALT

MBEDTLS_TEST_NULL_ENTROPY

Enables testing and use of Mbed TLS without any configured entropy sources. This permits use of the library on platforms before an entropy source has been integrated (see for example the MBEDTLS_ENTROPY_HARDWARE_ALT or the MBEDTLS_ENTROPY_NV_SEED switches).

WARNING! This switch MUST be disabled in production builds, and is suitable only for development. Enabling the switch negates any security provided by the library.

Requires MBEDTLS_ENTROPY_C, MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES

MBEDTLS_ENTROPY_HARDWARE_ALT

Uncomment this macro to let Mbed TLS use your own implementation of a hardware entropy collector.

Your function must be called mbedtls_hardware_poll(), have the same prototype as declared in entropy_poll.h, and accept NULL as first argument.

Uncomment to use your own hardware entropy collector.

MBEDTLS_AES_ROM_TABLES

Use precomputed AES tables stored in ROM.

Uncomment this macro to use precomputed AES tables stored in ROM. Comment this macro to generate AES tables in RAM at runtime.

Tradeoff: Using precomputed ROM tables reduces RAM usage by ~8kb (or ~2kb if MBEDTLS_AES_FEWER_TABLES is used) and reduces the initialization time before the first AES operation can be performed. It comes at the cost of additional ~8kb ROM use (resp. ~2kb if MBEDTLS_AES_FEWER_TABLES below is used), and potentially degraded performance if ROM access is slower than RAM access.

This option is independent of MBEDTLS_AES_FEWER_TABLES.

MBEDTLS_AES_FEWER_TABLES

Use less ROM/RAM for AES tables.

Uncommenting this macro omits 75% of the AES tables from ROM / RAM (depending on the value of MBEDTLS_AES_ROM_TABLES) by computing their values on the fly during operations (the tables are entry-wise rotations of one another).

Tradeoff: Uncommenting this reduces the RAM / ROM footprint by ~6kb but at the cost of more arithmetic operations during runtime. Specifically, one has to compare 4 accesses within different tables to 4 accesses with additional arithmetic operations within the same table. The performance gain/loss depends on the system and memory details.

This option is independent of MBEDTLS_AES_ROM_TABLES.

MBEDTLS_CAMELLIA_SMALL_MEMORY

Use less ROM for the Camellia implementation (saves about 768 bytes).

Uncomment this macro to use less memory for Camellia.

MBEDTLS_CHECK_RETURN_WARNING

If this macro is defined, emit a compile-time warning if application code calls a function without checking its return value, but the return value should generally be checked in portable applications.

This is only supported on platforms where MBEDTLS_CHECK_RETURN is implemented. Otherwise this option has no effect.

Uncomment to get warnings on using fallible functions without checking their return value.

Note

This feature is a work in progress. Warnings will be added to more functions in the future.

Note

A few functions are considered critical, and ignoring the return value of these functions will trigger a warning even if this macro is not defined. To completely disable return value check warnings, define MBEDTLS_CHECK_RETURN with an empty expansion.

MBEDTLS_CIPHER_MODE_CBC

Enable Cipher Block Chaining mode (CBC) for symmetric ciphers.

MBEDTLS_CIPHER_MODE_CFB

Enable Cipher Feedback mode (CFB) for symmetric ciphers.

MBEDTLS_CIPHER_MODE_CTR

Enable Counter Block Cipher mode (CTR) for symmetric ciphers.

MBEDTLS_CIPHER_MODE_OFB

Enable Output Feedback mode (OFB) for symmetric ciphers.

MBEDTLS_CIPHER_MODE_XTS

Enable Xor-encrypt-xor with ciphertext stealing mode (XTS) for AES.

MBEDTLS_CIPHER_NULL_CIPHER

Enable NULL cipher. Warning: Only do so when you know what you are doing. This allows for encryption or channels without any security!

Requires MBEDTLS_ENABLE_WEAK_CIPHERSUITES as well to enable the following ciphersuites: MBEDTLS_TLS_ECDH_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDH_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_NULL_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_WITH_NULL_SHA MBEDTLS_TLS_RSA_WITH_NULL_MD5 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_NULL_SHA MBEDTLS_TLS_PSK_WITH_NULL_SHA384 MBEDTLS_TLS_PSK_WITH_NULL_SHA256 MBEDTLS_TLS_PSK_WITH_NULL_SHA

Uncomment this macro to enable the NULL cipher and ciphersuites

MBEDTLS_CIPHER_PADDING_PKCS7

MBEDTLS_CIPHER_PADDING_XXX: Uncomment or comment macros to add support for specific padding modes in the cipher layer with cipher modes that support padding (e.g. CBC)

If you disable all padding modes, only full blocks can be used with CBC.

Enable padding modes in the cipher layer.

MBEDTLS_CIPHER_PADDING_ONE_AND_ZEROS

MBEDTLS_CIPHER_PADDING_ZEROS_AND_LEN

MBEDTLS_CIPHER_PADDING_ZEROS

MBEDTLS_CTR_DRBG_USE_128_BIT_KEY

Uncomment this macro to use a 128-bit key in the CTR_DRBG module. By default, CTR_DRBG uses a 256-bit key.

MBEDTLS_ENABLE_WEAK_CIPHERSUITES

Enable weak ciphersuites in SSL / TLS. Warning: Only do so when you know what you are doing. This allows for channels with virtually no security at all!

This enables the following ciphersuites: MBEDTLS_TLS_RSA_WITH_DES_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_DES_CBC_SHA

Uncomment this macro to enable weak ciphersuites

Warning

DES is considered a weak cipher and its use constitutes a security risk. We recommend considering stronger ciphers instead.

MBEDTLS_REMOVE_ARC4_CIPHERSUITES

Remove RC4 ciphersuites by default in SSL / TLS. This flag removes the ciphersuites based on RC4 from the default list as returned by mbedtls_ssl_list_ciphersuites(). However, it is still possible to enable (some of) them with mbedtls_ssl_conf_ciphersuites() by including them explicitly.

Uncomment this macro to remove RC4 ciphersuites by default.

MBEDTLS_REMOVE_3DES_CIPHERSUITES

Remove 3DES ciphersuites by default in SSL / TLS. This flag removes the ciphersuites based on 3DES from the default list as returned by mbedtls_ssl_list_ciphersuites(). However, it is still possible to enable (some of) them with mbedtls_ssl_conf_ciphersuites() by including them explicitly.

A man-in-the-browser attacker can recover authentication tokens sent through a TLS connection using a 3DES based cipher suite (see “On the Practical

(In-)Security of 64-bit Block Ciphers” by Karthikeyan Bhargavan and Gaëtan Leurent, see

https://sweet32.info/SWEET32_CCS16.pdf). If this attack falls in your threat model or you are unsure, then you should keep this option enabled to remove 3DES based cipher suites.

Comment this macro to keep 3DES in the default ciphersuite list.

MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED

Enable the verified implementations of ECDH primitives from Project Everest (currently only Curve25519). This feature changes the layout of ECDH contexts and therefore is a compatibility break for applications that access fields of a mbedtls_ecdh_context structure directly. See also MBEDTLS_ECDH_LEGACY_CONTEXT in include/mbedtls/ecdh.h.

The Everest code is provided under the Apache 2.0 license only; therefore enabling this option is not compatible with taking the library under the GPL v2.0-or-later license.

MBEDTLS_ECP_DP_SECP192R1_ENABLED

MBEDTLS_ECP_XXXX_ENABLED: Enables specific curves within the Elliptic Curve module. By default all supported curves are enabled.

Comment macros to disable the curve and functions for it

MBEDTLS_ECP_DP_SECP224R1_ENABLED

MBEDTLS_ECP_DP_SECP256R1_ENABLED

MBEDTLS_ECP_DP_SECP384R1_ENABLED

MBEDTLS_ECP_DP_SECP521R1_ENABLED

MBEDTLS_ECP_DP_SECP192K1_ENABLED

MBEDTLS_ECP_DP_SECP224K1_ENABLED

MBEDTLS_ECP_DP_SECP256K1_ENABLED

MBEDTLS_ECP_DP_BP256R1_ENABLED

MBEDTLS_ECP_DP_BP384R1_ENABLED

MBEDTLS_ECP_DP_BP512R1_ENABLED

MBEDTLS_ECP_DP_CURVE25519_ENABLED

MBEDTLS_ECP_DP_CURVE448_ENABLED

MBEDTLS_ECP_NIST_OPTIM

Enable specific ‘modulo p’ routines for each NIST prime. Depending on the prime and architecture, makes operations 4 to 8 times faster on the corresponding curve.

Comment this macro to disable NIST curves optimisation.

MBEDTLS_ECP_NO_INTERNAL_RNG

When this option is disabled, mbedtls_ecp_mul() will make use of an internal RNG when called with a NULL f_rng argument, in order to protect against some side-channel attacks.

This protection introduces a dependency of the ECP module on one of the DRBG modules. For very constrained implementations that don’t require this protection (for example, because you’re only doing signature verification, so not manipulating any secret, or because local/physical side-channel attacks are outside your threat model), it might be desirable to get rid of that dependency.

Uncomment this macro to disable some counter-measures in ECP.

Warning

Enabling this option makes some uses of ECP vulnerable to some side-channel attacks. Only enable it if you know that’s not a problem for your use case.

MBEDTLS_ECP_RESTARTABLE

Enable “non-blocking” ECC operations that can return early and be resumed.

This allows various functions to pause by returning MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module, MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in order to further progress and eventually complete their operation. This is controlled through mbedtls_ecp_set_max_ops() which limits the maximum number of ECC operations a function may perform before pausing; see mbedtls_ecp_set_max_ops() for more information.

This is useful in non-threaded environments if you want to avoid blocking for too long on ECC (and, hence, X.509 or SSL/TLS) operations.

This option:

• Adds xxx_restartable() variants of existing operations in the following modules, with corresponding restart context types:

  • ECP (for Short Weierstrass curves only): scalar multiplication (mul), linear combination (muladd);

  • ECDSA: signature generation & verification;

  • PK: signature generation & verification;

  • X509: certificate chain verification.

• Adds mbedtls_ecdh_enable_restart() in the ECDH module.

• Changes the behaviour of TLS 1.2 clients (not servers) when using the ECDHE-ECDSA key exchange (not other key exchanges) to make all ECC computations restartable:

  • ECDH operations from the key exchange, only for Short Weierstrass curves;

  • verification of the server’s key exchange signature;

  • verification of the server’s certificate chain;

  • generation of the client’s signature if client authentication is used, with an ECC key/certificate.

Requires: MBEDTLS_ECP_C

Uncomment this macro to enable restartable ECC computations.

Note

In the cases above, the usual SSL/TLS functions, such as mbedtls_ssl_handshake(), can now return MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS.

Note

This option only works with the default software implementation of elliptic curve functionality. It is incompatible with MBEDTLS_ECP_ALT, MBEDTLS_ECDH_XXX_ALT, MBEDTLS_ECDSA_XXX_ALT, MBEDTLS_ECDH_LEGACY_CONTEXT, and MBEDTLS_USE_PSA_CRYPTO.

MBEDTLS_ECDH_LEGACY_CONTEXT

Use a backward compatible ECDH context.

Mbed TLS supports two formats for ECDH contexts (mbedtls_ecdh_context defined in ecdh.h). For most applications, the choice of format makes no difference, since all library functions can work with either format, except that the new format is incompatible with MBEDTLS_ECP_RESTARTABLE.

The new format used when this option is disabled is smaller (56 bytes on a 32-bit platform). In future versions of the library, it will support alternative implementations of ECDH operations. The new format is incompatible with applications that access context fields directly and with restartable ECP operations.

Define this macro if you enable MBEDTLS_ECP_RESTARTABLE or if you want to access ECDH context fields directly. Otherwise you should comment out this macro definition.

This option has no effect if MBEDTLS_ECDH_C is not enabled.

Note

This configuration option is experimental. Future versions of the library may modify the way the ECDH context layout is configured and may modify the layout of the new context type.

MBEDTLS_ECDSA_DETERMINISTIC

Enable deterministic ECDSA (RFC 6979). Standard ECDSA is “fragile” in the sense that lack of entropy when signing may result in a compromise of the long-term signing key. This is avoided by the deterministic variant.

Requires: MBEDTLS_HMAC_DRBG_C, MBEDTLS_ECDSA_C

Comment this macro to disable deterministic ECDSA.

MBEDTLS_KEY_EXCHANGE_PSK_ENABLED

Enable the PSK based ciphersuite modes in SSL / TLS.

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_PSK_WITH_RC4_128_SHA

MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED

Enable the DHE-PSK based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_DHM_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA

Warning

Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.

MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED

Enable the ECDHE-PSK based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECDH_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_RC4_128_SHA

MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED

Enable the RSA-PSK based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA

MBEDTLS_KEY_EXCHANGE_RSA_ENABLED

Enable the RSA-only based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_RSA_WITH_RC4_128_SHA MBEDTLS_TLS_RSA_WITH_RC4_128_MD5

MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED

Enable the DHE-RSA based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_DHM_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA

Warning

Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.

MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED

Enable the ECDHE-RSA based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_RC4_128_SHA

MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED

Enable the ECDHE-ECDSA based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C,

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA

MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED

Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384

MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED

Enable the ECDH-RSA based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_X509_CRT_PARSE_C

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_RSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384

MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED

Enable the ECJPAKE based ciphersuite modes in SSL / TLS.

Requires: MBEDTLS_ECJPAKE_C MBEDTLS_SHA256_C MBEDTLS_ECP_DP_SECP256R1_ENABLED

This enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8

Warning

This is currently experimental. EC J-PAKE support is based on the Thread v1.0.0 specification; incompatible changes to the specification might still happen. For this reason, this is disabled by default.

MBEDTLS_PK_PARSE_EC_EXTENDED

Enhance support for reading EC keys using variants of SEC1 not allowed by RFC 5915 and RFC 5480.

Currently this means parsing the SpecifiedECDomain choice of EC parameters (only known groups are supported, not arbitrary domains, to avoid validation issues).

Disable if you only need to support RFC 5915 + 5480 key formats.

MBEDTLS_ERROR_STRERROR_DUMMY

Enable a dummy error function to make use of mbedtls_strerror() in third party libraries easier when MBEDTLS_ERROR_C is disabled (no effect when MBEDTLS_ERROR_C is enabled).

You can safely disable this if MBEDTLS_ERROR_C is enabled, or if you’re not using mbedtls_strerror() or error_strerror() in your application.

Disable if you run into name conflicts and want to really remove the mbedtls_strerror()

MBEDTLS_GENPRIME

Enable the prime-number generation code.

Requires: MBEDTLS_BIGNUM_C

MBEDTLS_FS_IO

Enable functions that use the filesystem.

MBEDTLS_NO_DEFAULT_ENTROPY_SOURCES

Do not add default entropy sources. These are the platform specific, mbedtls_timing_hardclock and HAVEGE based poll functions.

This is useful to have more control over the added entropy sources in an application.

Uncomment this macro to prevent loading of default entropy functions.

MBEDTLS_NO_PLATFORM_ENTROPY

Do not use built-in platform entropy functions. This is useful if your platform does not support standards like the /dev/urandom or Windows CryptoAPI.

Uncomment this macro to disable the built-in platform entropy functions.

MBEDTLS_ENTROPY_FORCE_SHA256

Force the entropy accumulator to use a SHA-256 accumulator instead of the default SHA-512 based one (if both are available).

Requires: MBEDTLS_SHA256_C

On 32-bit systems SHA-256 can be much faster than SHA-512. Use this option if you have performance concerns.

This option is only useful if both MBEDTLS_SHA256_C and MBEDTLS_SHA512_C are defined. Otherwise the available hash module is used.

MBEDTLS_ENTROPY_NV_SEED

Enable the non-volatile (NV) seed file-based entropy source. (Also enables the NV seed read/write functions in the platform layer)

This is crucial (if not required) on systems that do not have a cryptographic entropy source (in hardware or kernel) available.

Requires: MBEDTLS_ENTROPY_C, MBEDTLS_PLATFORM_C

Note

The read/write functions that are used by the entropy source are determined in the platform layer, and can be modified at runtime and/or compile-time depending on the flags (MBEDTLS_PLATFORM_NV_SEED_*) used.

Note

If you use the default implementation functions that read a seedfile with regular fopen(), please make sure you make a seedfile with the proper name (defined in MBEDTLS_PLATFORM_STD_NV_SEED_FILE) and at least MBEDTLS_ENTROPY_BLOCK_SIZE bytes in size that can be read from and written to or you will get an entropy source error! The default implementation will only use the first MBEDTLS_ENTROPY_BLOCK_SIZE bytes from the file.

Note

The entropy collector will write to the seed file before entropy is given to an external source, to update it.

MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER

MBEDTLS_MEMORY_DEBUG

Enable debugging of buffer allocator memory issues. Automatically prints (to stderr) all (fatal) messages on memory allocation issues. Enables function for ‘debug output’ of allocated memory.

Requires: MBEDTLS_MEMORY_BUFFER_ALLOC_C

Uncomment this macro to let the buffer allocator print out error messages.

MBEDTLS_MEMORY_BACKTRACE

Include backtrace information with each allocated block.

Requires: MBEDTLS_MEMORY_BUFFER_ALLOC_C GLIBC-compatible backtrace() and backtrace_symbols() support

Uncomment this macro to include backtrace information

MBEDTLS_PK_RSA_ALT_SUPPORT

Support external private RSA keys (eg from a HSM) in the PK layer.

Comment this macro to disable support for external private RSA keys.

MBEDTLS_PKCS1_V15

Enable support for PKCS#1 v1.5 encoding.

Requires: MBEDTLS_RSA_C

This enables support for PKCS#1 v1.5 operations.

MBEDTLS_PKCS1_V21

Enable support for PKCS#1 v2.1 encoding.

Requires: MBEDTLS_MD_C, MBEDTLS_RSA_C

This enables support for RSAES-OAEP and RSASSA-PSS operations.

MBEDTLS_PSA_CRYPTO_BUILTIN_KEYS

Enable support for platform built-in keys. If you enable this feature, you must implement the function mbedtls_psa_platform_get_builtin_key(). See the documentation of that function for more information.

Built-in keys are typically derived from a hardware unique key or stored in a secure element.

Requires: MBEDTLS_PSA_CRYPTO_C.

Warning

This interface is experimental and may change or be removed without notice.

MBEDTLS_PSA_CRYPTO_CLIENT

Enable support for PSA crypto client.

Note

This option allows to include the code necessary for a PSA crypto client when the PSA crypto implementation is not included in the library (MBEDTLS_PSA_CRYPTO_C disabled). The code included is the code to set and get PSA key attributes. The development of PSA drivers partially relying on the library to fulfill the hardware gaps is another possible usage of this option.

Warning

This interface is experimental and may change or be removed without notice.

MBEDTLS_PSA_CRYPTO_DRIVERS

Enable support for the experimental PSA crypto driver interface.

Requires: MBEDTLS_PSA_CRYPTO_C

Warning

This interface is experimental and may change or be removed without notice.

MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG

Make the PSA Crypto module use an external random generator provided by a driver, instead of Mbed TLS’s entropy and DRBG modules.

If you enable this option, you must configure the type mbedtls_psa_external_random_context_t in psa/crypto_platform.h and define a function called mbedtls_psa_external_get_random() with the following prototype:

psa_status_t mbedtls_psa_external_get_random(
    mbedtls_psa_external_random_context_t *context,
    uint8_t *output, size_t output_size, size_t *output_length);
);

The context value is initialized to 0 before the first call. The function must fill the output buffer with output_size bytes of random data and set *output_length to output_size.

Requires: MBEDTLS_PSA_CRYPTO_C

Note

This random generator must deliver random numbers with cryptographic quality and high performance. It must supply unpredictable numbers with a uniform distribution. The implementation of this function is responsible for ensuring that the random generator is seeded with sufficient entropy. If you have a hardware TRNG which is slow or delivers non-uniform output, declare it as an entropy source with mbedtls_entropy_add_source() instead of enabling this option.

Note

This option is experimental and may be removed without notice.

Warning

If you enable this option, code that uses the PSA cryptography interface will not use any of the entropy sources set up for the entropy module, nor the NV seed that MBEDTLS_ENTROPY_NV_SEED enables.

MBEDTLS_PSA_CRYPTO_SPM

When MBEDTLS_PSA_CRYPTO_SPM is defined, the code is built for SPM (Secure Partition Manager) integration which separates the code into two parts: a NSPE (Non-Secure Process Environment) and an SPE (Secure Process Environment).

Module: library/psa_crypto.c Requires: MBEDTLS_PSA_CRYPTO_C

MBEDTLS_PSA_INJECT_ENTROPY

Enable support for entropy injection at first boot. This feature is required on systems that do not have a built-in entropy source (TRNG). This feature is currently not supported on systems that have a built-in entropy source.

Requires: MBEDTLS_PSA_CRYPTO_STORAGE_C, MBEDTLS_ENTROPY_NV_SEED

MBEDTLS_PSA_ASSUME_EXCLUSIVE_BUFFERS

Assume all buffers passed to PSA functions are owned exclusively by the PSA function and are not stored in shared memory.

This option may be enabled if all buffers passed to any PSA function reside in memory that is accessible only to the PSA function during its execution.

This option MUST be disabled whenever buffer arguments are in memory shared with an untrusted party, for example where arguments to PSA calls are passed across a trust boundary.

Note

Enabling this option reduces memory usage and code size.

Note

Enabling this option causes overlap of input and output buffers not to be supported by PSA functions.

MBEDTLS_RSA_NO_CRT

Do not use the Chinese Remainder Theorem for the RSA private operation.

Uncomment this macro to disable the use of CRT in RSA.

MBEDTLS_SELF_TEST

Enable the checkup functions (*_self_test).

MBEDTLS_SHA256_SMALLER

Enable an implementation of SHA-256 that has lower ROM footprint but also lower performance.

The default implementation is meant to be a reasonable compromise between performance and size. This version optimizes more aggressively for size at the expense of performance. Eg on Cortex-M4 it reduces the size of mbedtls_sha256_process() from ~2KB to ~0.5KB for a performance hit of about 30%.

Uncomment to enable the smaller implementation of SHA256.

MBEDTLS_SHA512_SMALLER

Enable an implementation of SHA-512 that has lower ROM footprint but also lower performance.

Uncomment to enable the smaller implementation of SHA512.

MBEDTLS_SHA512_NO_SHA384

Disable the SHA-384 option of the SHA-512 module. Use this to save some code size on devices that don’t use SHA-384.

Requires: MBEDTLS_SHA512_C

Uncomment to disable SHA-384

MBEDTLS_SSL_ALL_ALERT_MESSAGES

Enable sending of alert messages in case of encountered errors as per RFC. If you choose not to send the alert messages, Mbed TLS can still communicate with other servers, only debugging of failures is harder.

The advantage of not sending alert messages, is that no information is given about reasons for failures thus preventing adversaries of gaining intel.

Enable sending of all alert messages

MBEDTLS_SSL_RECORD_CHECKING

Enable the function mbedtls_ssl_check_record() which can be used to check the validity and authenticity of an incoming record, to verify that it has not been seen before. These checks are performed without modifying the externally visible state of the SSL context.

See mbedtls_ssl_check_record() for more information.

Uncomment to enable support for record checking.

MBEDTLS_SSL_DTLS_CONNECTION_ID

Enable support for the DTLS Connection ID extension (version draft-ietf-tls-dtls-connection-id-05, https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05) which allows to identify DTLS connections across changes in the underlying transport.

Setting this option enables the SSL APIs mbedtls_ssl_set_cid(), mbedtls_ssl_get_peer_cid() and mbedtls_ssl_conf_cid(). See the corresponding documentation for more information.

The maximum lengths of outgoing and incoming CIDs can be configured through the options

• MBEDTLS_SSL_CID_OUT_LEN_MAX

• MBEDTLS_SSL_CID_IN_LEN_MAX.

Requires: MBEDTLS_SSL_PROTO_DTLS

Uncomment to enable the Connection ID extension.

Warning

The Connection ID extension is still in draft state. We make no stability promises for the availability or the shape of the API controlled by this option.

MBEDTLS_SSL_ASYNC_PRIVATE

Enable asynchronous external private key operations in SSL. This allows you to configure an SSL connection to call an external cryptographic module to perform private key operations instead of performing the operation inside the library.

MBEDTLS_SSL_CONTEXT_SERIALIZATION

Enable serialization of the TLS context structures, through use of the functions mbedtls_ssl_context_save() and mbedtls_ssl_context_load().

This pair of functions allows one side of a connection to serialize the context associated with the connection, then free or re-use that context while the serialized state is persisted elsewhere, and finally deserialize that state to a live context for resuming read/write operations on the connection. From a protocol perspective, the state of the connection is unaffected, in particular this is entirely transparent to the peer.

Note: this is distinct from TLS session resumption, which is part of the protocol and fully visible by the peer. TLS session resumption enables establishing new connections associated to a saved session with shorter, lighter handshakes, while context serialization is a local optimization in handling a single, potentially long-lived connection.

Enabling these APIs makes some SSL structures larger, as 64 extra bytes are saved after the handshake to allow for more efficient serialization, so if you don’t need this feature you’ll save RAM by disabling it.

Requires: MBEDTLS_GCM_C or MBEDTLS_CCM_C or MBEDTLS_CHACHAPOLY_C

Comment to disable the context serialization APIs.

MBEDTLS_SSL_DEBUG_ALL

Enable the debug messages in SSL module for all issues. Debug messages have been disabled in some places to prevent timing attacks due to (unbalanced) debugging function calls.

If you need all error reporting you should enable this during debugging, but remove this for production servers that should log as well.

Uncomment this macro to report all debug messages on errors introducing a timing side-channel.

MBEDTLS_SSL_ENCRYPT_THEN_MAC

Enable support for Encrypt-then-MAC, RFC 7366.

This allows peers that both support it to use a more robust protection for ciphersuites using CBC, providing deep resistance against timing attacks on the padding or underlying cipher.

This only affects CBC ciphersuites, and is useless if none is defined.

Requires: MBEDTLS_SSL_PROTO_TLS1 or MBEDTLS_SSL_PROTO_TLS1_1 or MBEDTLS_SSL_PROTO_TLS1_2

Comment this macro to disable support for Encrypt-then-MAC

MBEDTLS_SSL_EXTENDED_MASTER_SECRET

Enable support for RFC 7627: Session Hash and Extended Master Secret Extension.

This was introduced as “the proper fix” to the Triple Handshake family of attacks, but it is recommended to always use it (even if you disable renegotiation), since it actually fixes a more fundamental issue in the original SSL/TLS design, and has implications beyond Triple Handshake.

Requires: MBEDTLS_SSL_PROTO_TLS1 or MBEDTLS_SSL_PROTO_TLS1_1 or MBEDTLS_SSL_PROTO_TLS1_2

Comment this macro to disable support for Extended Master Secret.

MBEDTLS_SSL_FALLBACK_SCSV

Enable support for RFC 7507: Fallback Signaling Cipher Suite Value (SCSV) for Preventing Protocol Downgrade Attacks.

For servers, it is recommended to always enable this, unless you support only one version of TLS, or know for sure that none of your clients implements a fallback strategy.

For clients, you only need this if you’re using a fallback strategy, which is not recommended in the first place, unless you absolutely need it to interoperate with buggy (version-intolerant) servers.

Comment this macro to disable support for FALLBACK_SCSV

MBEDTLS_SSL_KEEP_PEER_CERTIFICATE

This option controls the availability of the API mbedtls_ssl_get_peer_cert() giving access to the peer’s certificate after completion of the handshake.

Unless you need mbedtls_ssl_peer_cert() in your application, it is recommended to disable this option for reduced RAM usage.

Comment this macro to disable storing the peer’s certificate after the handshake.

Note

If this option is disabled, mbedtls_ssl_get_peer_cert() is still defined, but always returns NULL.

Note

This option has no influence on the protection against the triple handshake attack. Even if it is disabled, Mbed TLS will still ensure that certificates do not change during renegotiation, for example by keeping a hash of the peer’s certificate.

MBEDTLS_SSL_HW_RECORD_ACCEL

Enable hooking functions in SSL module for hardware acceleration of individual records.

Deprecated:

This option is deprecated and will be removed in a future version of Mbed TLS.

Uncomment this macro to enable hooking functions.

MBEDTLS_SSL_CBC_RECORD_SPLITTING

Enable 1/n-1 record splitting for CBC mode in SSLv3 and TLS 1.0.

This is a countermeasure to the BEAST attack, which also minimizes the risk of interoperability issues compared to sending 0-length records.

Comment this macro to disable 1/n-1 record splitting.

MBEDTLS_SSL_RENEGOTIATION

Enable support for TLS renegotiation.

The two main uses of renegotiation are (1) refresh keys on long-lived connections and (2) client authentication after the initial handshake. If you don’t need renegotiation, it’s probably better to disable it, since it has been associated with security issues in the past and is easy to misuse/misunderstand.

Comment this to disable support for renegotiation.

Note

Even if this option is disabled, both client and server are aware of the Renegotiation Indication Extension (RFC 5746) used to prevent the SSL renegotiation attack (see RFC 5746 Sect. 1). (See mbedtls_ssl_conf_legacy_renegotiation for the configuration of this extension).

MBEDTLS_SSL_SRV_SUPPORT_SSLV2_CLIENT_HELLO

Enable support for receiving and parsing SSLv2 Client Hello messages for the SSL Server module (MBEDTLS_SSL_SRV_C).

Deprecated:

This option is deprecated and will be removed in a future version of Mbed TLS.

Uncomment this macro to enable support for SSLv2 Client Hello messages.

MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE

Pick the ciphersuite according to the client’s preferences rather than ours in the SSL Server module (MBEDTLS_SSL_SRV_C).

Uncomment this macro to respect client’s ciphersuite order

MBEDTLS_SSL_MAX_FRAGMENT_LENGTH

Enable support for RFC 6066 max_fragment_length extension in SSL.

Comment this macro to disable support for the max_fragment_length extension

MBEDTLS_SSL_PROTO_SSL3

Enable support for SSL 3.0.

Requires: MBEDTLS_MD5_C MBEDTLS_SHA1_C

Deprecated:

This option is deprecated and will be removed in a future version of Mbed TLS.

Comment this macro to disable support for SSL 3.0

MBEDTLS_SSL_PROTO_TLS1

Enable support for TLS 1.0.

Requires: MBEDTLS_MD5_C MBEDTLS_SHA1_C

Comment this macro to disable support for TLS 1.0

MBEDTLS_SSL_PROTO_TLS1_1

Enable support for TLS 1.1 (and DTLS 1.0 if DTLS is enabled).

Requires: MBEDTLS_MD5_C MBEDTLS_SHA1_C

Comment this macro to disable support for TLS 1.1 / DTLS 1.0

MBEDTLS_SSL_PROTO_TLS1_2

Enable support for TLS 1.2 (and DTLS 1.2 if DTLS is enabled).

Requires: MBEDTLS_SHA1_C or MBEDTLS_SHA256_C or MBEDTLS_SHA512_C (Depends on ciphersuites)

Comment this macro to disable support for TLS 1.2 / DTLS 1.2

MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL

This macro is used to selectively enable experimental parts of the code that contribute to the ongoing development of the prototype TLS 1.3 and DTLS 1.3 implementation, and provide no other purpose.

Uncomment this macro to enable experimental and partial functionality specific to TLS 1.3.

Warning

TLS 1.3 and DTLS 1.3 aren’t yet supported in Mbed TLS, and no feature exposed through this macro is part of the public API. In particular, features under the control of this macro are experimental and don’t come with any stability guarantees.

MBEDTLS_SSL_PROTO_DTLS

Enable support for DTLS (all available versions).

Enable this and MBEDTLS_SSL_PROTO_TLS1_1 to enable DTLS 1.0, and/or this and MBEDTLS_SSL_PROTO_TLS1_2 to enable DTLS 1.2.

Requires: MBEDTLS_SSL_PROTO_TLS1_1 or MBEDTLS_SSL_PROTO_TLS1_2

Comment this macro to disable support for DTLS

MBEDTLS_SSL_ALPN

Enable support for RFC 7301 Application Layer Protocol Negotiation.

Comment this macro to disable support for ALPN.

MBEDTLS_SSL_DTLS_ANTI_REPLAY

Enable support for the anti-replay mechanism in DTLS.

Requires: MBEDTLS_SSL_TLS_C MBEDTLS_SSL_PROTO_DTLS

Comment this to disable anti-replay in DTLS.

Warning

Disabling this is often a security risk! See mbedtls_ssl_conf_dtls_anti_replay() for details.

MBEDTLS_SSL_DTLS_HELLO_VERIFY

Enable support for HelloVerifyRequest on DTLS servers.

This feature is highly recommended to prevent DTLS servers being used as amplifiers in DoS attacks against other hosts. It should always be enabled unless you know for sure amplification cannot be a problem in the environment in which your server operates.

Requires: MBEDTLS_SSL_PROTO_DTLS

Comment this to disable support for HelloVerifyRequest.

Warning

Disabling this can be a security risk! (see above)

MBEDTLS_SSL_DTLS_SRTP

Enable support for negotiation of DTLS-SRTP (RFC 5764) through the use_srtp extension.

Setting this option enables the runtime API mbedtls_ssl_conf_dtls_srtp_protection_profiles() through which the supported DTLS-SRTP protection profiles can be configured. You must call this API at runtime if you wish to negotiate the use of DTLS-SRTP.

Requires: MBEDTLS_SSL_PROTO_DTLS

Uncomment this to enable support for use_srtp extension.

Note

This feature provides the minimum functionality required to negotiate the use of DTLS-SRTP and to allow the derivation of the associated SRTP packet protection key material. In particular, the SRTP packet protection itself, as well as the demultiplexing of RTP and DTLS packets at the datagram layer (see Section 5 of RFC 5764), are not handled by this feature. Instead, after successful completion of a handshake negotiating the use of DTLS-SRTP, the extended key exporter API mbedtls_ssl_conf_export_keys_ext_cb() should be used to implement the key exporter described in Section 4.2 of RFC 5764 and RFC 5705 (this is implemented in the SSL example programs). The resulting key should then be passed to an SRTP stack.

MBEDTLS_SSL_DTLS_CLIENT_PORT_REUSE

Enable server-side support for clients that reconnect from the same port.

Some clients unexpectedly close the connection and try to reconnect using the same source port. This needs special support from the server to handle the new connection securely, as described in section 4.2.8 of RFC 6347. This flag enables that support.

Requires: MBEDTLS_SSL_DTLS_HELLO_VERIFY

Comment this to disable support for clients reusing the source port.

MBEDTLS_SSL_DTLS_BADMAC_LIMIT

Enable support for a limit of records with bad MAC.

See mbedtls_ssl_conf_dtls_badmac_limit().

Requires: MBEDTLS_SSL_PROTO_DTLS

MBEDTLS_SSL_SESSION_TICKETS

Enable support for RFC 5077 session tickets in SSL. Client-side, provides full support for session tickets (maintenance of a session store remains the responsibility of the application, though). Server-side, you also need to provide callbacks for writing and parsing tickets, including authenticated encryption and key management. Example callbacks are provided by MBEDTLS_SSL_TICKET_C.

Comment this macro to disable support for SSL session tickets

MBEDTLS_SSL_EXPORT_KEYS

Enable support for exporting key block and master secret. This is required for certain users of TLS, e.g. EAP-TLS.

Comment this macro to disable support for key export

MBEDTLS_SSL_SERVER_NAME_INDICATION

Enable support for RFC 6066 server name indication (SNI) in SSL.

Requires: MBEDTLS_X509_CRT_PARSE_C

Comment this macro to disable support for server name indication in SSL

MBEDTLS_SSL_TRUNCATED_HMAC

Enable support for RFC 6066 truncated HMAC in SSL.

Comment this macro to disable support for truncated HMAC in SSL

MBEDTLS_SSL_TRUNCATED_HMAC_COMPAT

Fallback to old (pre-2.7), non-conforming implementation of the truncated HMAC extension which also truncates the HMAC key. Note that this option is only meant for a transitory upgrade period and will be removed in a future version of the library.

Deprecated:

This option is deprecated and will be removed in a future version of Mbed TLS.

Uncomment to fallback to old, non-compliant truncated HMAC implementation.

Requires: MBEDTLS_SSL_TRUNCATED_HMAC

Warning

The old implementation is non-compliant and has a security weakness (2^80 brute force attack on the HMAC key used for a single, uninterrupted connection). This should only be enabled temporarily when (1) the use of truncated HMAC is essential in order to save bandwidth, and (2) the peer is an Mbed TLS stack that doesn’t use the fixed implementation yet (pre-2.7).

MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH

When this option is enabled, the SSL buffer will be resized automatically based on the negotiated maximum fragment length in each direction.

Requires: MBEDTLS_SSL_MAX_FRAGMENT_LENGTH

MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE

Allow SHA-1 in the default TLS configuration for TLS 1.2 handshake signature and ciphersuite selection. Without this build-time option, SHA-1 support must be activated explicitly through mbedtls_ssl_conf_sig_hashes. The use of SHA-1 in TLS <= 1.1 and in HMAC-SHA-1 is always allowed by default. At the time of writing, there is no practical attack on the use of SHA-1 in handshake signatures, hence this option is turned on by default to preserve compatibility with existing peers, but the general warning applies nonetheless:

Warning

SHA-1 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.

MBEDTLS_TEST_CONSTANT_FLOW_MEMSAN

Enable testing of the constant-flow nature of some sensitive functions with clang’s MemorySanitizer. This causes some existing tests to also test this non-functional property of the code under test.

This setting requires compiling with clang -fsanitize=memory. The test suites can then be run normally.

Uncomment to enable testing of the constant-flow nature of selected code.

Warning

This macro is only used for extended testing; it is not considered part of the library’s API, so it may change or disappear at any time.

MBEDTLS_TEST_CONSTANT_FLOW_VALGRIND

Enable testing of the constant-flow nature of some sensitive functions with valgrind’s memcheck tool. This causes some existing tests to also test this non-functional property of the code under test.

This setting requires valgrind headers for building, and is only useful for testing if the tests suites are run with valgrind’s memcheck. This can be done for an individual test suite with ‘valgrind ./test_suite_xxx’, or when using CMake, this can be done for all test suites with ‘make memcheck’.

Uncomment to enable testing of the constant-flow nature of selected code.

Warning

This macro is only used for extended testing; it is not considered part of the library’s API, so it may change or disappear at any time.

MBEDTLS_TEST_HOOKS

Enable features for invasive testing such as introspection functions and hooks for fault injection. This enables additional unit tests.

Merely enabling this feature should not change the behavior of the product. It only adds new code, and new branching points where the default behavior is the same as when this feature is disabled. However, this feature increases the attack surface: there is an added risk of vulnerabilities, and more gadgets that can make exploits easier. Therefore this feature must never be enabled in production.

See docs/architecture/testing/mbed-crypto-invasive-testing.md for more information.

Uncomment to enable invasive tests.

MBEDTLS_THREADING_ALT

Provide your own alternate threading implementation.

Requires: MBEDTLS_THREADING_C

Uncomment this to allow your own alternate threading implementation.

MBEDTLS_THREADING_PTHREAD

Enable the pthread wrapper layer for the threading layer.

Requires: MBEDTLS_THREADING_C

Uncomment this to enable pthread mutexes.

MBEDTLS_USE_PSA_CRYPTO

Make the X.509 and TLS library use PSA for cryptographic operations, and enable new APIs for using keys handled by PSA Crypto.

Requires: MBEDTLS_PSA_CRYPTO_C.

Uncomment this to enable internal use of PSA Crypto and new associated APIs.

Note

Development of this option is currently in progress, and parts of Mbed TLS’s X.509 and TLS modules are not ported to PSA yet. However, these parts will still continue to work as usual, so enabling this option should not break backwards compatibility.

Note

See docs/use-psa-crypto.md for a complete description of what this option currently does, and of parts that are not affected by it so far.

Warning

This option enables new Mbed TLS APIs which are currently considered experimental and may change in incompatible ways at any time. That is, the APIs enabled by this option are not covered by the usual promises of API stability.

MBEDTLS_PSA_CRYPTO_CONFIG

This setting allows support for cryptographic mechanisms through the PSA API to be configured separately from support through the mbedtls API.

When this option is disabled, the PSA API exposes the cryptographic mechanisms that can be implemented on top of the mbedtls_xxx API configured with MBEDTLS_XXX symbols.

When this option is enabled, the PSA API exposes the cryptographic mechanisms requested by the PSA_WANT_XXX symbols defined in include/psa/crypto_config.h. The corresponding MBEDTLS_XXX settings are automatically enabled if required (i.e. if no PSA driver provides the mechanism). You may still freely enable additional MBEDTLS_XXX symbols in config.h.

If the symbol MBEDTLS_PSA_CRYPTO_CONFIG_FILE is defined, it specifies an alternative header to include instead of include/psa/crypto_config.h.

If you enable this option and write your own configuration file, you must include mbedtls/config_psa.h in your configuration file. The default provided mbedtls/config.h contains the necessary inclusion.

This feature is still experimental and is not ready for production since it is not completed.

MBEDTLS_VERSION_FEATURES

Allow run-time checking of compile-time enabled features. Thus allowing users to check at run-time if the library is for instance compiled with threading support via mbedtls_version_check_feature().

Requires: MBEDTLS_VERSION_C

Comment this to disable run-time checking and save ROM space

MBEDTLS_X509_ALLOW_EXTENSIONS_NON_V3

If set, the X509 parser will not break-off when parsing an X509 certificate and encountering an extension in a v1 or v2 certificate.

Uncomment to prevent an error.

MBEDTLS_X509_ALLOW_UNSUPPORTED_CRITICAL_EXTENSION

If set, the X509 parser will not break-off when parsing an X509 certificate and encountering an unknown critical extension.

Uncomment to prevent an error.

Warning

Depending on your PKI use, enabling this can be a security risk!

MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK

If set, this enables the X.509 API mbedtls_x509_crt_verify_with_ca_cb() and the SSL API mbedtls_ssl_conf_ca_cb() which allow users to configure the set of trusted certificates through a callback instead of a linked list.

This is useful for example in environments where a large number of trusted certificates is present and storing them in a linked list isn’t efficient enough, or when the set of trusted certificates changes frequently.

See the documentation of mbedtls_x509_crt_verify_with_ca_cb() and mbedtls_ssl_conf_ca_cb() for more information.

Uncomment to enable trusted certificate callbacks.

MBEDTLS_X509_CHECK_KEY_USAGE

Enable verification of the keyUsage extension (CA and leaf certificates).

Disabling this avoids problems with mis-issued and/or misused (intermediate) CA and leaf certificates.

Comment to skip keyUsage checking for both CA and leaf certificates.

Warning

Depending on your PKI use, disabling this can be a security risk!

MBEDTLS_X509_CHECK_EXTENDED_KEY_USAGE

Enable verification of the extendedKeyUsage extension (leaf certificates).

Disabling this avoids problems with mis-issued and/or misused certificates.

Comment to skip extendedKeyUsage checking for certificates.

Warning

Depending on your PKI use, disabling this can be a security risk!

MBEDTLS_X509_RSASSA_PSS_SUPPORT

Enable parsing and verification of X.509 certificates, CRLs and CSRS signed with RSASSA-PSS (aka PKCS#1 v2.1).

Comment this macro to disallow using RSASSA-PSS in certificates.

MBEDTLS_ZLIB_SUPPORT

If set, the SSL/TLS module uses ZLIB to support compression and decompression of packet data.

Deprecated:

This feature is deprecated and will be removed in the next major revision of the library.

Used in: library/ssl_tls.c library/ssl_cli.c library/ssl_srv.c

This feature requires zlib library and headers to be present.

Uncomment to enable use of ZLIB

Note

Currently compression can’t be used with DTLS.

Warning

TLS-level compression MAY REDUCE SECURITY! See for example the CRIME attack. Before enabling this option, you should examine with care if CRIME or similar exploits may be applicable to your use case.

SECTION: Mbed TLS modules

This section enables or disables entire modules in Mbed TLS

MBEDTLS_AESNI_C

Enable AES-NI support on x86-64 or x86-32.

Module: library/aesni.c Caller: library/aes.c

Requires: MBEDTLS_HAVE_ASM (on some platforms, see note)

This modules adds support for the AES-NI instructions on x86.

Note

AESNI is only supported with certain compilers and target options:

• Visual Studio 2013: supported.

• GCC, x86-64, target not explicitly supporting AESNI: requires MBEDTLS_HAVE_ASM.

• GCC, x86-32, target not explicitly supporting AESNI: not supported.

• GCC, x86-64 or x86-32, target supporting AESNI: supported. For this assembly-less implementation, you must currently compile library/aesni.c and library/aes.c with machine options to enable SSE2 and AESNI instructions: gcc -msse2 -maes -mpclmul or clang -maes -mpclmul.

• Non-x86 targets: this option is silently ignored.

• Other compilers: this option is silently ignored.

Note

Above, “GCC” includes compatible compilers such as Clang. The limitations on target support are likely to be relaxed in the future.

MBEDTLS_AES_C

Enable the AES block cipher.

Module: library/aes.c Caller: library/cipher.c library/pem.c library/ctr_drbg.c

This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_AES_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_AES_128_CBC_SHA MBEDTLS_TLS_PSK_WITH_AES_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA MBEDTLS_TLS_PSK_WITH_AES_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA

PEM_PARSE uses AES for decrypting encrypted keys.

MBEDTLS_ARC4_C

Enable the ARCFOUR stream cipher.

Module: library/arc4.c Caller: library/cipher.c

This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDH_RSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_RC4_128_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_RC4_128_SHA MBEDTLS_TLS_DHE_PSK_WITH_RC4_128_SHA MBEDTLS_TLS_RSA_WITH_RC4_128_SHA MBEDTLS_TLS_RSA_WITH_RC4_128_MD5 MBEDTLS_TLS_RSA_PSK_WITH_RC4_128_SHA MBEDTLS_TLS_PSK_WITH_RC4_128_SHA

Warning

ARC4 is considered a weak cipher and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger ciphers instead.

MBEDTLS_ASN1_PARSE_C

Enable the generic ASN1 parser.

Module: library/asn1.c Caller: library/x509.c library/dhm.c library/pkcs12.c library/pkcs5.c library/pkparse.c

MBEDTLS_ASN1_WRITE_C

Enable the generic ASN1 writer.

Module: library/asn1write.c Caller: library/ecdsa.c library/pkwrite.c library/x509_create.c library/x509write_crt.c library/x509write_csr.c

MBEDTLS_BASE64_C

Enable the Base64 module.

Module: library/base64.c Caller: library/pem.c

This module is required for PEM support (required by X.509).

MBEDTLS_BIGNUM_C

Enable the multi-precision integer library.

Module: library/bignum.c Caller: library/dhm.c library/ecp.c library/ecdsa.c library/rsa.c library/rsa_internal.c library/ssl_tls.c

This module is required for RSA, DHM and ECC (ECDH, ECDSA) support.

MBEDTLS_BLOWFISH_C

Enable the Blowfish block cipher.

Module: library/blowfish.c

MBEDTLS_CAMELLIA_C

Enable the Camellia block cipher.

Module: library/camellia.c Caller: library/cipher.c

This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDH_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_DHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_256_CBC_SHA MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_RSA_WITH_CAMELLIA_128_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_RSA_PSK_WITH_CAMELLIA_128_CBC_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256

MBEDTLS_ARIA_C

Enable the ARIA block cipher.

Module: library/aria.c Caller: library/cipher.c

This module enables the following ciphersuites (if other requisites are enabled as well):

 MBEDTLS_TLS_RSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_RSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_RSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_RSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_DHE_RSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_ECDH_ECDSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_ECDH_RSA_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_PSK_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_PSK_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_CBC_SHA384
 MBEDTLS_TLS_PSK_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_PSK_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_DHE_PSK_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_128_GCM_SHA256
 MBEDTLS_TLS_RSA_PSK_WITH_ARIA_256_GCM_SHA384
 MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256
 MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384

MBEDTLS_CCM_C

Enable the Counter with CBC-MAC (CCM) mode for 128-bit block cipher.

Module: library/ccm.c

Requires: MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C

This module enables the AES-CCM ciphersuites, if other requisites are enabled as well.

MBEDTLS_CERTS_C

Enable the test certificates.

Module: library/certs.c Caller:

This module is used for testing (ssl_client/server).

MBEDTLS_CHACHA20_C

Enable the ChaCha20 stream cipher.

Module: library/chacha20.c

MBEDTLS_CHACHAPOLY_C

Enable the ChaCha20-Poly1305 AEAD algorithm.

Module: library/chachapoly.c

This module requires: MBEDTLS_CHACHA20_C, MBEDTLS_POLY1305_C

MBEDTLS_CIPHER_C

Enable the generic cipher layer.

Module: library/cipher.c Caller: library/ssl_tls.c

Uncomment to enable generic cipher wrappers.

MBEDTLS_CMAC_C

Enable the CMAC (Cipher-based Message Authentication Code) mode for block ciphers.

Module: library/cmac.c

Requires: MBEDTLS_AES_C or MBEDTLS_DES_C

Note

When MBEDTLS_CMAC_ALT is active, meaning that the underlying implementation of the CMAC algorithm is provided by an alternate implementation, that alternate implementation may opt to not support AES-192 or 3DES as underlying block ciphers for the CMAC operation.

MBEDTLS_CTR_DRBG_C

Enable the CTR_DRBG AES-based random generator. The CTR_DRBG generator uses AES-256 by default. To use AES-128 instead, enable MBEDTLS_CTR_DRBG_USE_128_BIT_KEY above.

Module: library/ctr_drbg.c Caller:

Requires: MBEDTLS_AES_C

This module provides the CTR_DRBG AES random number generator.

Note

To achieve a 256-bit security strength with CTR_DRBG, you must use AES-256 and use sufficient entropy. See ctr_drbg.h for more details.

MBEDTLS_DEBUG_C

Enable the debug functions.

Module: library/debug.c Caller: library/ssl_cli.c library/ssl_srv.c library/ssl_tls.c

This module provides debugging functions.

MBEDTLS_DES_C

Enable the DES block cipher.

Module: library/des.c Caller: library/pem.c library/cipher.c

This module enables the following ciphersuites (if other requisites are enabled as well): MBEDTLS_TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_ECDHE_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_DHE_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_RSA_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_RSA_PSK_WITH_3DES_EDE_CBC_SHA MBEDTLS_TLS_PSK_WITH_3DES_EDE_CBC_SHA

PEM_PARSE uses DES/3DES for decrypting encrypted keys.

Warning

DES/3DES are considered weak ciphers and their use constitutes a security risk. We recommend considering stronger ciphers instead.

MBEDTLS_DHM_C

Enable the Diffie-Hellman-Merkle module.

Module: library/dhm.c Caller: library/ssl_cli.c library/ssl_srv.c

This module is used by the following key exchanges: DHE-RSA, DHE-PSK

Warning

Using DHE constitutes a security risk as it is not possible to validate custom DH parameters. If possible, it is recommended users should consider preferring other methods of key exchange. See dhm.h for more details.

MBEDTLS_ECDH_C

Enable the elliptic curve Diffie-Hellman library.

Module: library/ecdh.c Caller: library/ssl_cli.c library/ssl_srv.c

This module is used by the following key exchanges: ECDHE-ECDSA, ECDHE-RSA, DHE-PSK

Requires: MBEDTLS_ECP_C

MBEDTLS_ECDSA_C

Enable the elliptic curve DSA library.

Module: library/ecdsa.c Caller:

This module is used by the following key exchanges: ECDHE-ECDSA

Requires: MBEDTLS_ECP_C, MBEDTLS_ASN1_WRITE_C, MBEDTLS_ASN1_PARSE_C, and at least one MBEDTLS_ECP_DP_XXX_ENABLED for a short Weierstrass curve.

MBEDTLS_ECJPAKE_C

Enable the elliptic curve J-PAKE library.

Module: library/ecjpake.c Caller:

This module is used by the following key exchanges: ECJPAKE

Requires: MBEDTLS_ECP_C, MBEDTLS_MD_C

Warning

This is currently experimental. EC J-PAKE support is based on the Thread v1.0.0 specification; incompatible changes to the specification might still happen. For this reason, this is disabled by default.

MBEDTLS_ECP_C

Enable the elliptic curve over GF(p) library.

Module: library/ecp.c Caller: library/ecdh.c library/ecdsa.c library/ecjpake.c

Requires: MBEDTLS_BIGNUM_C and at least one MBEDTLS_ECP_DP_XXX_ENABLED

MBEDTLS_ENTROPY_C

Enable the platform-specific entropy code.

Module: library/entropy.c Caller:

Requires: MBEDTLS_SHA512_C or MBEDTLS_SHA256_C

This module provides a generic entropy pool

MBEDTLS_ERROR_C

Enable error code to error string conversion.

Module: library/error.c Caller:

This module enables mbedtls_strerror().

MBEDTLS_GCM_C

Enable the Galois/Counter Mode (GCM).

Module: library/gcm.c

Requires: MBEDTLS_AES_C or MBEDTLS_CAMELLIA_C or MBEDTLS_ARIA_C

This module enables the AES-GCM and CAMELLIA-GCM ciphersuites, if other requisites are enabled as well.

MBEDTLS_HAVEGE_C

Enable the HAVEGE random generator.

Warning: the HAVEGE random generator is not suitable for virtualized environments

Warning: the HAVEGE random generator is dependent on timing and specific processor traits. It is therefore not advised to use HAVEGE as your applications primary random generator or primary entropy pool input. As a secondary input to your entropy pool, it IS able add the (limited) extra entropy it provides.

Module: library/havege.c Caller:

Requires: MBEDTLS_TIMING_C

Uncomment to enable the HAVEGE random generator.

MBEDTLS_HKDF_C

Enable the HKDF algorithm (RFC 5869).

Module: library/hkdf.c Caller:

Requires: MBEDTLS_MD_C

This module adds support for the Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF).

MBEDTLS_HMAC_DRBG_C

Enable the HMAC_DRBG random generator.

Module: library/hmac_drbg.c Caller:

Requires: MBEDTLS_MD_C

Uncomment to enable the HMAC_DRBG random number generator.

MBEDTLS_NIST_KW_C

Enable the Key Wrapping mode for 128-bit block ciphers, as defined in NIST SP 800-38F. Only KW and KWP modes are supported. At the moment, only AES is approved by NIST.

Module: library/nist_kw.c

Requires: MBEDTLS_AES_C and MBEDTLS_CIPHER_C

MBEDTLS_MD_C

Enable the generic message digest layer.

Module: library/md.c Caller:

Uncomment to enable generic message digest wrappers.

MBEDTLS_MD2_C

Enable the MD2 hash algorithm.

Module: library/md2.c Caller:

Uncomment to enable support for (rare) MD2-signed X.509 certs.

Warning

MD2 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.

MBEDTLS_MD4_C

Enable the MD4 hash algorithm.

Module: library/md4.c Caller:

Uncomment to enable support for (rare) MD4-signed X.509 certs.

Warning

MD4 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.

MBEDTLS_MD5_C

Enable the MD5 hash algorithm.

Module: library/md5.c Caller: library/md.c library/pem.c library/ssl_tls.c

This module is required for SSL/TLS up to version 1.1, and for TLS 1.2 depending on the handshake parameters. Further, it is used for checking MD5-signed certificates, and for PBKDF1 when decrypting PEM-encoded encrypted keys.

Warning

MD5 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.

MBEDTLS_MEMORY_BUFFER_ALLOC_C

Enable the buffer allocator implementation that makes use of a (stack) based buffer to ‘allocate’ dynamic memory. (replaces calloc() and free() calls)

Module: library/memory_buffer_alloc.c

Requires: MBEDTLS_PLATFORM_C MBEDTLS_PLATFORM_MEMORY (to use it within Mbed TLS)

Enable this module to enable the buffer memory allocator.

MBEDTLS_NET_C

Enable the TCP and UDP over IPv6/IPv4 networking routines.

Module: library/net_sockets.c

This module provides networking routines.

Note

This module only works on POSIX/Unix (including Linux, BSD and OS X) and Windows. For other platforms, you’ll want to disable it, and write your own networking callbacks to be passed to mbedtls_ssl_set_bio().

Note

See also our Knowledge Base article about porting to a new environment: https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS

MBEDTLS_OID_C

Enable the OID database.

Module: library/oid.c Caller: library/asn1write.c library/pkcs5.c library/pkparse.c library/pkwrite.c library/rsa.c library/x509.c library/x509_create.c library/x509_crl.c library/x509_crt.c library/x509_csr.c library/x509write_crt.c library/x509write_csr.c

This modules translates between OIDs and internal values.

MBEDTLS_PADLOCK_C

Enable VIA Padlock support on x86.

Module: library/padlock.c Caller: library/aes.c

Requires: MBEDTLS_HAVE_ASM

This modules adds support for the VIA PadLock on x86.

MBEDTLS_PEM_PARSE_C

Enable PEM decoding / parsing.

Module: library/pem.c Caller: library/dhm.c library/pkparse.c library/x509_crl.c library/x509_crt.c library/x509_csr.c

Requires: MBEDTLS_BASE64_C

This modules adds support for decoding / parsing PEM files.

MBEDTLS_PEM_WRITE_C

Enable PEM encoding / writing.

Module: library/pem.c Caller: library/pkwrite.c library/x509write_crt.c library/x509write_csr.c

Requires: MBEDTLS_BASE64_C

This modules adds support for encoding / writing PEM files.

MBEDTLS_PK_C

Enable the generic public (asymmetric) key layer.

Module: library/pk.c Caller: library/ssl_tls.c library/ssl_cli.c library/ssl_srv.c

Requires: MBEDTLS_RSA_C or MBEDTLS_ECP_C

Uncomment to enable generic public key wrappers.

MBEDTLS_PK_PARSE_C

Enable the generic public (asymmetric) key parser.

Module: library/pkparse.c Caller: library/x509_crt.c library/x509_csr.c

Requires: MBEDTLS_PK_C

Uncomment to enable generic public key parse functions.

MBEDTLS_PK_WRITE_C

Enable the generic public (asymmetric) key writer.

Module: library/pkwrite.c Caller: library/x509write.c

Requires: MBEDTLS_PK_C

Uncomment to enable generic public key write functions.

MBEDTLS_PKCS5_C

Enable PKCS#5 functions.

Module: library/pkcs5.c

Requires: MBEDTLS_MD_C

This module adds support for the PKCS#5 functions.

MBEDTLS_PKCS11_C

Enable wrapper for PKCS#11 smartcard support via the pkcs11-helper library.

Deprecated:

This option is deprecated and will be removed in a future version of Mbed TLS.

Module: library/pkcs11.c Caller: library/pk.c

Requires: MBEDTLS_PK_C

This module enables SSL/TLS PKCS #11 smartcard support. Requires the presence of the PKCS#11 helper library (libpkcs11-helper)

MBEDTLS_PKCS12_C

Enable PKCS#12 PBE functions. Adds algorithms for parsing PKCS#8 encrypted private keys

Module: library/pkcs12.c Caller: library/pkparse.c

Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_CIPHER_C, MBEDTLS_MD_C Can use: MBEDTLS_ARC4_C

This module enables PKCS#12 functions.

MBEDTLS_PLATFORM_C

Enable the platform abstraction layer that allows you to re-assign functions like calloc(), free(), snprintf(), printf(), fprintf(), exit().

Enabling MBEDTLS_PLATFORM_C enables to use of MBEDTLS_PLATFORM_XXX_ALT or MBEDTLS_PLATFORM_XXX_MACRO directives, allowing the functions mentioned above to be specified at runtime or compile time respectively.

Module: library/platform.c Caller: Most other .c files

This module enables abstraction of common (libc) functions.

Note

This abstraction layer must be enabled on Windows (including MSYS2) as other module rely on it for a fixed snprintf implementation.

MBEDTLS_POLY1305_C

Enable the Poly1305 MAC algorithm.

Module: library/poly1305.c Caller: library/chachapoly.c

MBEDTLS_PSA_CRYPTO_C

Enable the Platform Security Architecture cryptography API.

Module: library/psa_crypto.c

Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C, or MBEDTLS_HMAC_DRBG_C and MBEDTLS_ENTROPY_C, or MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.

MBEDTLS_PSA_CRYPTO_SE_C

Enable secure element support in the Platform Security Architecture cryptography API.

Module: library/psa_crypto_se.c

Requires: MBEDTLS_PSA_CRYPTO_C, MBEDTLS_PSA_CRYPTO_STORAGE_C

Warning

This feature is not yet suitable for production. It is provided for API evaluation and testing purposes only.

MBEDTLS_PSA_CRYPTO_STORAGE_C

Enable the Platform Security Architecture persistent key storage.

Module: library/psa_crypto_storage.c

Requires: MBEDTLS_PSA_CRYPTO_C, either MBEDTLS_PSA_ITS_FILE_C or a native implementation of the PSA ITS interface

MBEDTLS_PSA_ITS_FILE_C

Enable the emulation of the Platform Security Architecture Internal Trusted Storage (PSA ITS) over files.

Module: library/psa_its_file.c

Requires: MBEDTLS_FS_IO

MBEDTLS_RIPEMD160_C

Enable the RIPEMD-160 hash algorithm.

Module: library/ripemd160.c Caller: library/md.c

MBEDTLS_RSA_C

Enable the RSA public-key cryptosystem.

Module: library/rsa.c library/rsa_internal.c Caller: library/ssl_cli.c library/ssl_srv.c library/ssl_tls.c library/x509.c

This module is used by the following key exchanges: RSA, DHE-RSA, ECDHE-RSA, RSA-PSK

Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C

MBEDTLS_SHA1_C

Enable the SHA1 cryptographic hash algorithm.

Module: library/sha1.c Caller: library/md.c library/ssl_cli.c library/ssl_srv.c library/ssl_tls.c library/x509write_crt.c

This module is required for SSL/TLS up to version 1.1, for TLS 1.2 depending on the handshake parameters, and for SHA1-signed certificates.

Warning

SHA-1 is considered a weak message digest and its use constitutes a security risk. If possible, we recommend avoiding dependencies on it, and considering stronger message digests instead.

MBEDTLS_SHA256_C

Enable the SHA-224 and SHA-256 cryptographic hash algorithms.

Module: library/sha256.c Caller: library/entropy.c library/md.c library/ssl_cli.c library/ssl_srv.c library/ssl_tls.c

This module adds support for SHA-224 and SHA-256. This module is required for the SSL/TLS 1.2 PRF function.

MBEDTLS_SHA512_C

Enable the SHA-384 and SHA-512 cryptographic hash algorithms.

Module: library/sha512.c Caller: library/entropy.c library/md.c library/ssl_cli.c library/ssl_srv.c

This module adds support for SHA-384 and SHA-512.

MBEDTLS_SSL_CACHE_C

Enable simple SSL cache implementation.

Module: library/ssl_cache.c Caller:

Requires: MBEDTLS_SSL_CACHE_C

MBEDTLS_SSL_COOKIE_C

Enable basic implementation of DTLS cookies for hello verification.

Module: library/ssl_cookie.c Caller:

MBEDTLS_SSL_TICKET_C

Enable an implementation of TLS server-side callbacks for session tickets.

Module: library/ssl_ticket.c Caller:

Requires: MBEDTLS_CIPHER_C && ( MBEDTLS_GCM_C || MBEDTLS_CCM_C || MBEDTLS_CHACHAPOLY_C )

MBEDTLS_SSL_CLI_C

Enable the SSL/TLS client code.

Module: library/ssl_cli.c Caller:

Requires: MBEDTLS_SSL_TLS_C

This module is required for SSL/TLS client support.

MBEDTLS_SSL_SRV_C

Enable the SSL/TLS server code.

Module: library/ssl_srv.c Caller:

Requires: MBEDTLS_SSL_TLS_C

This module is required for SSL/TLS server support.

MBEDTLS_SSL_TLS_C

Enable the generic SSL/TLS code.

Module: library/ssl_tls.c Caller: library/ssl_cli.c library/ssl_srv.c

Requires: MBEDTLS_CIPHER_C, MBEDTLS_MD_C and at least one of the MBEDTLS_SSL_PROTO_XXX defines

This module is required for SSL/TLS.

MBEDTLS_THREADING_C

Enable the threading abstraction layer. By default Mbed TLS assumes it is used in a non-threaded environment or that contexts are not shared between threads. If you do intend to use contexts between threads, you will need to enable this layer to prevent race conditions. See also our Knowledge Base article about threading: https://mbed-tls.readthedocs.io/en/latest/kb/development/thread-safety-and-multi-threading

Module: library/threading.c

This allows different threading implementations (self-implemented or provided).

You will have to enable either MBEDTLS_THREADING_ALT or MBEDTLS_THREADING_PTHREAD.

Enable this layer to allow use of mutexes within Mbed TLS

MBEDTLS_TIMING_C

Enable the semi-portable timing interface.

Module: library/timing.c Caller: library/havege.c

This module is used by the HAVEGE random number generator.

Note

The provided implementation only works on POSIX/Unix (including Linux, BSD and OS X) and Windows. On other platforms, you can either disable that module and provide your own implementations of the callbacks needed by mbedtls_ssl_set_timer_cb() for DTLS, or leave it enabled and provide your own implementation of the whole module by setting MBEDTLS_TIMING_ALT in the current file.

Note

The timing module will include time.h on suitable platforms regardless of the setting of MBEDTLS_HAVE_TIME, unless MBEDTLS_TIMING_ALT is used. See timing.c for more information.

Note

See also our Knowledge Base article about porting to a new environment: https://mbed-tls.readthedocs.io/en/latest/kb/how-to/how-do-i-port-mbed-tls-to-a-new-environment-OS

MBEDTLS_VERSION_C

Enable run-time version information.

Module: library/version.c

This module provides run-time version information.

MBEDTLS_X509_USE_C

Enable X.509 core for using certificates.

Module: library/x509.c Caller: library/x509_crl.c library/x509_crt.c library/x509_csr.c

Requires: MBEDTLS_ASN1_PARSE_C, MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_PARSE_C

This module is required for the X.509 parsing modules.

MBEDTLS_X509_CRT_PARSE_C

Enable X.509 certificate parsing.

Module: library/x509_crt.c Caller: library/ssl_cli.c library/ssl_srv.c library/ssl_tls.c

Requires: MBEDTLS_X509_USE_C

This module is required for X.509 certificate parsing.

MBEDTLS_X509_CRL_PARSE_C

Enable X.509 CRL parsing.

Module: library/x509_crl.c Caller: library/x509_crt.c

Requires: MBEDTLS_X509_USE_C

This module is required for X.509 CRL parsing.

MBEDTLS_X509_CSR_PARSE_C

Enable X.509 Certificate Signing Request (CSR) parsing.

Module: library/x509_csr.c Caller: library/x509_crt_write.c

Requires: MBEDTLS_X509_USE_C

This module is used for reading X.509 certificate request.

MBEDTLS_X509_CREATE_C

Enable X.509 core for creating certificates.

Module: library/x509_create.c

Requires: MBEDTLS_BIGNUM_C, MBEDTLS_OID_C, MBEDTLS_PK_WRITE_C

This module is the basis for creating X.509 certificates and CSRs.

MBEDTLS_X509_CRT_WRITE_C

Enable creating X.509 certificates.

Module: library/x509_crt_write.c

Requires: MBEDTLS_X509_CREATE_C

This module is required for X.509 certificate creation.

MBEDTLS_X509_CSR_WRITE_C

Enable creating X.509 Certificate Signing Requests (CSR).

Module: library/x509_csr_write.c

Requires: MBEDTLS_X509_CREATE_C

This module is required for X.509 certificate request writing.

MBEDTLS_XTEA_C

Enable the XTEA block cipher.

Module: library/xtea.c Caller:

SECTION: General configuration options

This section contains Mbed TLS build settings that are not associated with a particular module.

MBEDTLS_CONFIG_FILE

If defined, this is a header which will be included instead of "mbedtls/config.h". This header file specifies the compile-time configuration of Mbed TLS. Unlike other configuration options, this one must be defined on the compiler command line: a definition in config.h would have no effect.

This macro is expanded after an #include directive. This is a popular but non-standard feature of the C language, so this feature is only available with compilers that perform macro expansion on an #include line.

The value of this symbol is typically a path in double quotes, either absolute or relative to a directory on the include search path.

MBEDTLS_USER_CONFIG_FILE

If defined, this is a header which will be included after "mbedtls/config.h" or MBEDTLS_CONFIG_FILE. This allows you to modify the default configuration, including the ability to undefine options that are enabled by default.

This macro is expanded after an #include directive. This is a popular but non-standard feature of the C language, so this feature is only available with compilers that perform macro expansion on an #include line.

The value of this symbol is typically a path in double quotes, either absolute or relative to a directory on the include search path.

MBEDTLS_PSA_CRYPTO_CONFIG_FILE

If defined, this is a header which will be included instead of "psa/crypto_config.h". This header file specifies which cryptographic mechanisms are available through the PSA API when MBEDTLS_PSA_CRYPTO_CONFIG is enabled, and is not used when MBEDTLS_PSA_CRYPTO_CONFIG is disabled.

This macro is expanded after an #include directive. This is a popular but non-standard feature of the C language, so this feature is only available with compilers that perform macro expansion on an #include line.

The value of this symbol is typically a path in double quotes, either absolute or relative to a directory on the include search path.

MBEDTLS_PSA_CRYPTO_USER_CONFIG_FILE

If defined, this is a header which will be included after "psa/crypto_config.h" or MBEDTLS_PSA_CRYPTO_CONFIG_FILE. This allows you to modify the default configuration, including the ability to undefine options that are enabled by default.

This macro is expanded after an #include directive. This is a popular but non-standard feature of the C language, so this feature is only available with compilers that perform macro expansion on an #include line.

The value of this symbol is typically a path in double quotes, either absolute or relative to a directory on the include search path.