`Mbed TLS <https://github.com/Mbed-TLS/mbedtls>`_ is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
ESP-IDF uses a `fork <https://github.com/espressif/mbedtls>`_ of Mbed TLS which includes a few patches (related to hardware routines of certain modules like ``bignum (MPI)`` and ``ECC``) over vanilla Mbed TLS.
Mbed TLS v3.x.x series supports only TLS 1.2 and TLS 1.3 protocols. Support for SSL 3.0, TLS 1.0/1.1 and DTLS 1.0 has been removed (deprecated). TLS 1.3 is fully supported starting Mbed TLS v3.6.0 release, before this release some features were still in experimental state. Please refer to :component_file:`Mbed TLS ChangeLog <mbedtls/mbedtls/ChangeLog>` for more details.
Please find the information about the Mbed TLS versions presented in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
ESP-IDF provides a preset-based configuration system for Mbed TLS to simplify setup and provide optimized starting points for different use cases. This system works alongside the existing manual configuration system and provides baseline configurations that can be further customized through menuconfig or additional configuration files.
..list-table::
:header-rows:1
:widths:15 25 35
:align:center
* - Preset
- Use Case
- Key Features
* - **Default**
- General purpose applications
- • TLS 1.2 & 1.3 support
• Certificate bundle enabled
• Hardware acceleration
• Full cipher suite support
* - **Minimal**
- Resource-constrained applications
- • TLS 1.2 client only
• RSA & PSK key exchange
• AES-128 CBC/CTR modes
• Basic X.509 parsing
* - **Bluetooth (BT)**
- Bluetooth applications
- • Optimized for BLE security
• ECC P-256 curve support
• Minimal TLS overhead
• Bluetooth-specific algorithms
Using Configuration Presets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Presets serve as **starting points** for your mbedTLS configuration. You can use them as-is or customize them further using standard ESP-IDF configuration methods.
To use a preset configuration, add the following line to your project's ``CMakeLists.txt`` file **before** the ``project()`` call:
..code-block:: cmake
# Include the default preset (recommended for most applications)
Examples in ESP-IDF use :doc:`/api-reference/protocols/esp_tls` which provides a simplified API interface for accessing the commonly used TLS functionality.
Refer to the examples :example:`protocols/https_server/simple` (Simple HTTPS server) and :example:`protocols/https_request` (Make HTTPS requests) for more information.
If you plan to use the Mbed TLS API directly, refer to the example :example:`protocols/https_mbedtls`. This example demonstrates how to establish an HTTPS connection using Mbed TLS by setting up a secure socket with a certificate bundle for verification.
:doc:`/api-reference/protocols/esp_tls` acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at `<https://github.com/espressif/esp-wolfSSL>` with the upstream submodule pointer.
Please refer to :ref:`ESP-TLS: Underlying SSL/TLS Library Options <esp_tls_wolfssl>` docs for more information on this and comparison of Mbed TLS and wolfSSL.
The Mbed TLS configuration system supports preset configurations. Following is a brief list of important config options accessible at ``Component Config -> mbedTLS``. The full list of config options can be found :ref:`here <CONFIG_MBEDTLS_MEM_ALLOC_MODE>`.
-:ref:`CONFIG_MBEDTLS_DEBUG`: Enable mbedTLS debugging (useful for development)
**TLS Protocol Configuration:**
..list::
-:ref:`CONFIG_MBEDTLS_TLS_ENABLED`: Enable TLS protocol support
-:ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`: Support for TLS 1.2 (recommended)
-:ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`: Support for TLS 1.3 (latest standard)
-:ref:`CONFIG_MBEDTLS_SSL_PROTO_DTLS`: Support for DTLS (UDP-based TLS)
-:ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Client session tickets
-:ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: Support for TLS Session Resumption: Server session tickets
-:ref:`CONFIG_MBEDTLS_SSL_ALPN`: Support for Application Layer Protocol Negotiation
-:ref:`CONFIG_MBEDTLS_SSL_SERVER_NAME_INDICATION`: Support for Server Name Indication (SNI)
**Certificate Support:**
..list::
-:ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: Support for trusted root certificate bundle (more about this: :doc:`/api-reference/protocols/esp_crt_bundle`)
-:ref:`CONFIG_MBEDTLS_X509_USE_C`: Enable X.509 certificate support
-:ref:`CONFIG_MBEDTLS_SHA256_C`: SHA-256 hash function
-:ref:`CONFIG_MBEDTLS_SHA512_C`: SHA-512 hash function
-:ref:`CONFIG_MBEDTLS_GCM_C`: Galois/Counter Mode for authenticated encryption
..note::
The new configuration structure provides better organization with categories like "Core Configuration", "TLS Protocol Configuration", "Symmetric Ciphers", "Asymmetric Ciphers", "Hash Functions", and "Hardware Acceleration" for easier navigation and configuration management.
Debugging mbedTLS
^^^^^^^^^^^^^^^^^
To enable debugging, add these configurations:
..code-block:: kconfig
CONFIG_MBEDTLS_DEBUG=y
CONFIG_MBEDTLS_DEBUG_LEVEL=3
CONFIG_LOG_DEFAULT_LEVEL_DEBUG=y
Performance Optimization
^^^^^^^^^^^^^^^^^^^^^^^^
For optimal performance **Enable hardware acceleration** when available:
The following table shows typical memory usage with different configs when the :example:`protocols/https_request` example (with Server Validation enabled) was run with Mbed TLS as the SSL/TLS library.
Under ``Component Config -> mbedTLS``, there are multiple Mbed TLS features which are enabled by default but can be disabled if not needed to save code size. More information can be about this can be found in :ref:`Minimizing Binary Size <minimizing_binary_mbedtls>` docs.
