ESP-IDF 使用的 Mbed TLS `复刻仓库 <https://github.com/espressif/mbedtls>`_ 中包含对原生 Mbed TLS 的补丁。这些补丁与某些模块的硬件例程有关，如 ``bignum (MPI)`` 和 ``ECC``。

Mbed TLS v3.x.x 系列仅支持 TLS 1.2 和 TLS 1.3 协议。对 SSL 3.0、TLS 1.0/1.1 和 DTLS 1.0 的支持已被删除（弃用）。从 Mbed TLS v3.6.0 版本开始完全支持 TLS 1.3，在此版本之前，某些功能仍处于试验状态。有关更多详细信息，请参阅 :component_file:`Mbed TLS ChangeLog <mbedtls/mbedtls/ChangeLog>`。

参考 :ref:`migration_guide_mbedtls` 从 Mbed TLS 2.x 版本迁移到 3.0 及以上版本。

* - 预设
  - 使用场景
  - 主要特性
* - **默认**
  - 通用应用
  - • 支持 TLS 1.2 和 1.3
    • 启用证书包
    • 硬件加速
    • 支持完整的加密算法套件
* - **最小化**
  - 资源受限应用
  - • 仅 TLS 1.2 客户端
    • RSA 和 PSK 密钥交换
    • AES-128 CBC/CTR 模式
    • 基本的 X.509 解析
* - **蓝牙 (BT)**
  - 蓝牙应用
  - • 针对低功耗蓝牙安全性需求进行优化
    • 支持 ECC P-256 曲线
    • 最小的 TLS 开销
    • 蓝牙特定算法

# 包含默认预设（适用于大多数应用）
list(APPEND sdkconfig_defaults $ENV{IDF_PATH}/components/mbedtls/config/mbedtls_preset_default.conf)

# 适用于资源受限的应用
list(APPEND sdkconfig_defaults $ENV{IDF_PATH}/components/mbedtls/config/mbedtls_preset_minimal.conf)

# 适用于蓝牙应用
list(APPEND sdkconfig_defaults $ENV{IDF_PATH}/components/mbedtls/config/mbedtls_preset_bt.conf)

# 标准的 ESP-IDF 项目设置
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

预设配置存放于 ``components/mbedtls/config/`` 中，你可以自定义预设配置或将其作为基础模板使用。

# 在 CMakeLists.txt 中应用预设后
idf.py menuconfig

# 基于最小预设，添加自定义设置
list(APPEND SDKCONFIG_DEFAULTS
    $ENV{IDF_PATH}/components/mbedtls/config/mbedtls_preset_minimal.conf
    ${CMAKE_CURRENT_SOURCE_DIR}/my_custom_mbedtls.conf
)

:SOC_SHA_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`：支持硬件 SHA 加速
:SOC_AES_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`：支持硬件 AES 加速
:SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`：支持硬件 MPI（大数）加速
:SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`：支持硬件 ECC 加速
- :ref:`CONFIG_MBEDTLS_MEM_ALLOC_MODE`：内存分配策略（内部/外部/自定义）
- :ref:`CONFIG_MBEDTLS_ASYMMETRIC_CONTENT_LEN`：用于内存优化的非对称输入/输出片段长度
- :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`：启用动态 TX/RX buffer 分配
- :ref:`CONFIG_MBEDTLS_DEBUG`：启用 mbedTLS 调试（有助于调试）

- :ref:`CONFIG_MBEDTLS_TLS_ENABLED`：启用 TLS 协议支持
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`：支持 TLS 1.2（推荐）
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`：支持 TLS 1.3（最新标准）
- :ref:`CONFIG_MBEDTLS_SSL_PROTO_DTLS`：支持基于 UDP 的 DTLS
- :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`：支持 TLS 会话恢复（客户端会话票据）
- :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`：支持 TLS 会话恢复（服务器会话票据）
- :ref:`CONFIG_MBEDTLS_SSL_ALPN`：支持应用层协议协商
- :ref:`CONFIG_MBEDTLS_SSL_SERVER_NAME_INDICATION`：支持服务器名称指示 (SNI)

- :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`：支持受信任的根证书包（详情请参阅 :doc:`/api-reference/protocols/esp_crt_bundle`）
- :ref:`CONFIG_MBEDTLS_X509_USE_C`：启用 X.509 证书支持
- :ref:`CONFIG_MBEDTLS_PEM_PARSE_C`：读取并解析 PEM 格式的证书
- :ref:`CONFIG_MBEDTLS_PEM_WRITE_C`：编写 PEM 格式的证书
- :ref:`CONFIG_MBEDTLS_X509_CRT_PARSE_C`：解析 X.509 证书
- :ref:`CONFIG_MBEDTLS_X509_CRL_PARSE_C`：解析 X.509 证书吊销列表

- :ref:`CONFIG_MBEDTLS_AES_C`：支持 AES 块密码
- :ref:`CONFIG_MBEDTLS_RSA_C`：RSA 公钥密码系统
- :ref:`CONFIG_MBEDTLS_ECP_C`：支持椭圆曲线密码学
- :ref:`CONFIG_MBEDTLS_ECDSA_C`：椭圆曲线数字签名算法
- :ref:`CONFIG_MBEDTLS_ECDH_C`：椭圆曲线 Diffie-Hellman 密钥交换
- :ref:`CONFIG_MBEDTLS_SHA256_C`：SHA-256 哈希函数
- :ref:`CONFIG_MBEDTLS_SHA512_C`：SHA-512 哈希函数
- :ref:`CONFIG_MBEDTLS_GCM_C`：Galois/Counter 模式用于认证加密

新的配置结构将各项配置按照“核心配置”、“TLS 协议配置”、“对称加密算法”、“非对称加密算法”、“哈希函数”和“硬件加速”等类别进行分类，便于查找和管理配置。

CONFIG_MBEDTLS_DEBUG=y
CONFIG_MBEDTLS_DEBUG_LEVEL=3
CONFIG_LOG_DEFAULT_LEVEL_DEBUG=y

CONFIG_MBEDTLS_HARDWARE_AES=y
CONFIG_MBEDTLS_HARDWARE_SHA=y
CONFIG_MBEDTLS_HARDWARE_MPI=y
CONFIG_MBEDTLS_HARDWARE_ECC=y

* - Mbed TLS 测试
  - 相关配置
  - 堆使用（近似值）
* - 默认
  - NA
  - 42196 B
* - 启用 SSL 动态 buffer 长度
  - :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH`
  -  42120 B
* - 禁用保留对端证书
  - :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`
  - 38533 B
* - 启用动态 TX/RX buffer
  - :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`
    :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`
    ::ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`
  - 22013 B

这些值会随着配置选项和 Mbed TLS 版本的变化而变化。