警告

This document is not updated for ESP32H21 yet, so some of the content may not be correct.

This warning was automatically inserted due to the source file being in the add_warnings_pages list.

# Mbed TLS

[English]

Mbed TLS 是一个 C 代码库，用于实现加密基元、X.509 证书操作以及 SSL/TLS 和 DTLS 协议。该库代码占用空间小，适合嵌入式系统使用。

备注

ESP-IDF 使用的 Mbed TLS 复刻仓库 中包含对原生 Mbed TLS 的补丁。这些补丁与某些模块的硬件例程有关，如 `bignum (MPI)` 和 `ECC`。

Mbed TLS 通过提供以下内容支持 TLS 1.2、TLS 1.3 和 DTLS 1.2 通信：

- TCP/IP 通信功能：监听、连接、接收、读/写。

- SSL/TLS 通信功能：初始化、握手、读/写。

- X.509 功能：CRT、CRL 和密钥处理

- 随机数生成

- 哈希

- 加密/解密

备注

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，在此版本之前，某些功能仍处于试验状态。有关更多详细信息，请参阅 Mbed TLS ChangeLog 。

## Mbed TLS 文档

Mbed TLS 文档请参阅以下（上游）指针：

- API Reference

- Knowledge Base

## ESP-IDF 的 Mbed TLS 支持

请在 此处 查找 ESP-IDF 不同分支上的 Mbed TLS 版本信息。

备注

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

## 应用示例

ESP-IDF 中的示例使用 ESP-TLS，为访问常用的 TLS 功能提供了一个简化 API 接口。

参考示例 protocols/https_server/simple （简单的 HTTPS 服务器）和 protocols/https_request （发出 HTTPS 请求）了解更多信息。

如需直接使用 Mbed TLS API，请参考示例 protocols/https_mbedtls。该示例演示了如何通过 Mbed TLS 设置安全套接字，并使用证书包进行验证，从而建立 HTTPS 连接。

## 其他选项

ESP-TLS 是底层 SSL/TLS 库的抽象层，因此可以选择使用 Mbed TLS 或 wolfSSL 作为底层库。默认情况下，仅 Mbed TLS 可在 ESP-IDF 中使用，而 wolfSSL 在 https://github.com/espressif/esp-wolfSSL 公开，还提供了上游子模块指针的相关信息。

如需了解更多相关信息或比较 Mbed TLS 和 wolfSSL，请参考文档 ESP-TLS: Underlying SSL/TLS Library Options。

## 重要配置

`Component Config -> mbedTLS` 中的部分重要配置选项如下表所示。点击 此处 获取完整配置选项列表。

- CONFIG_MBEDTLS_SSL_PROTO_TLS1_2: 支持 TLS 1.2

- CONFIG_MBEDTLS_SSL_PROTO_TLS1_3: 支持 TLS 1.3

- CONFIG_MBEDTLS_CERTIFICATE_BUNDLE: 支持受信任的根证书包（更多信息请参考 ESP x509 证书包）

- CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS: 支持 TLS 会话恢复：客户端会话票证

- CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS: 支持 TLS 会话恢复：服务会话票证

- CONFIG_MBEDTLS_HARDWARE_SHA: 支持硬件 SHA 加速

- CONFIG_MBEDTLS_HARDWARE_AES: 支持硬件 AES 加速

- CONFIG_MBEDTLS_HARDWARE_MPI: 支持硬件 MPI (bignum) 加速

- CONFIG_MBEDTLS_HARDWARE_ECC: 支持硬件 ECC 加速

## 性能和内存调整

### 减少内存使用

下表展示了在不同配置下，用 Mbed TLS 作为 SSL/TLS 库运行示例 protocols/https_request （启用服务器验证）时，内存的实际使用情况。

Mbed TLS 测试 | 相关配置 | 堆使用（近似）
--- | --- | ---
默认 | NA | 42196 B
启用 SSL 动态 buffer 长度 | CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | 42120 B
禁用保留对端证书 | CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | 38533 B
启用动态 buffer 功能 | CONFIG_MBEDTLS_DYNAMIC_BUFFER CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT | 22013 B

备注

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

### 减小固件大小

在 `Component Config -> mbedTLS` 中，有多个 Mbed TLS 功能默认为启用状态。如果不需要这些功能，可将其禁用以减小固件大小。要了解更多信息，请参考 Minimizing Binary Size 文档。

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。