# 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) 加速

## 性能和内存调整

### 减少内存使用

下表展示了在不同配置下，用 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 文档。

此文档对您有帮助吗？

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

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