Mbed TLS

[English]

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

备注

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

Mbed TLS 提供以下功能:

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

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

  • X.509 功能:CRT、CRL 和密钥处理

  • 随机数生成

  • 哈希

  • 加密/解密

TLS 版本支持 SSL 3.0, TLS 1.0、TLS 1.1、TLS 1.2 和 TLS 1.3,但是最新的 ESP-IDF 上 Mbed TLS 已经移除了 SSL 3.0、TLS 1.0 和 TLS 1.1。DTLS 版本支持 DTLS 1.0、DTLS 1.1 和 DTLS 1.2,但最新的 ESP-IDF 上 Mbed TLS 已经移除了 DTLS 1.0。

Mbed TLS 文档

Mbed TLS 文档请参阅以下(上游)指针:

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

其他选项

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 中的部分重要配置选项如下表所示。点击 此处 获取完整配置选项列表。

备注

Mbed TLS v3.0.0 及其更新版本仅支持 TLS 1.2 和 TLS 1.3,不支持 SSL 3.0、TLS 1.0、TLS 1.1、和 DTLS 1.0)。TLS 1.3 尚在试验阶段,仅支持客户端。要了解更多信息,请点击 此处

性能和内存调整

减少内存使用

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