ESP x509 证书包

[English]

概述

ESP x509 证书包 API 提供了一种简便的方法，帮助你安装自定义 x509 根证书用于 TLS 服务器验证。

备注

目前在使用 WolfSSL 时该证书包不可用。

该证书包中包括 Mozilla NSS 根证书存储区的完整根证书列表。使用 gen_crt_bundle.py python 程序，可将证书的主题名称和公钥存储在文件中，并嵌入 ESP32-H2 二进制文件。

生成证书包时，你需选择：

  • 来自 Mozilla 的完整根证书包，包含超过 130 份证书。目前提供的证书包更新于 2024 年 3 月 11 日，星期一，15:25:27 (GMT)。

  • 一组预先筛选的常用根证书。其中仅包含约 41 份证书，但根据 SSL 证书颁发机构统计数据，其绝对使用率约达到 90%，市场覆盖率约达 99%。

此外，还可指定证书文件的路径或包含证书的目录，将其他证书添加到生成的证书包中。

备注

信任所有根证书意味着如果任何证书被收回，就必须更新证书列表，包括从 cacrt_all.pem 中将其删除。

配置

多数配置可通过 menuconfig 完成。CMake 会根据配置信息生成及嵌入证书包。

要在使用 ESP-TLS 时启用证书包，将函数指针指向证书包的 attach 函数：

esp_tls_cfg_t cfg = {
     .crt_bundle_attach = esp_crt_bundle_attach,
};

此步骤是为了避免在用户未使能的情况下嵌入证书包。

如果直接使用 mbedTLS 包，在设置阶段直接调用 attach 函数可以激活证书包：

mbedtls_ssl_config conf;
mbedtls_ssl_config_init(&conf);

esp_crt_bundle_attach(&conf);

生成根证书列表

根证书列表来自 Mozilla 的 NSS 根证书商店。

运行 mk-ca-bundle.pl 脚本可下载和创建列表。脚本发布于 curl。

还可通过 curl 网站直接下载完整列表： 从 Mozilla 提取的 CA 证书。

常用证书包是通过筛选出市场份额超过 1% 的授权机构来决定的，筛选数据来自 w3tech 的 SSL Survey。

根据这些授权机构，从 Mozilla 提供的 列表 的 cmn_crt_authorities.csv 中筛选证书名称。

更新证书包

证书包嵌入到应用程序中，通过 OTA 更新与应用程序一起更新。如果想使用比目前 ESP-IDF 中的证书包更新的包，则可按照 生成根证书列表 中的说明从 Mozilla 下载证书列表。

定期同步

证书包会与 Mozilla 的 NSS 根证书商店定期同步。在 ESP-IDF 的次要版本或补丁版本中，为了保证兼容性，会将上游证书包中已弃用的证书添加到弃用列表。如有需要，可以通过 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEPRECATED_LIST 将弃用证书加入默认证书包。这些弃用证书将在下一个 ESP-IDF 主要版本中移除。

应用示例

使用 ESP-TLS 创建安全套接字连接的简单 HTTPS 示例：protocols/https_x509_bundle，该示例使用了证书包并添加了两个自定义证书用于验证。

使用 ESP-TLS 和默认证书包的 HTTPS 示例：protocols/https_request。

使用 mbedTLS 和默认证书包的 HTTPS 示例：protocols/https_mbedtls。

API 参考

Header File

  • components/mbedtls/esp_crt_bundle/include/esp_crt_bundle.h

  • This header file can be included with:

    #include "esp_crt_bundle.h"

  • This header file is a part of the API provided by the mbedtls component. To declare that your component depends on mbedtls, add the following to your CMakeLists.txt:

    REQUIRES mbedtls

    or

    PRIV_REQUIRES mbedtls

Functions

esp_err_t esp_crt_bundle_attach(void *conf)

Attach and enable use of a bundle for certificate verification.

Attach and enable use of a bundle for certificate verification through a verification callback. If no specific bundle has been set through esp_crt_bundle_set() it will default to the bundle defined in menuconfig and embedded in the binary.

参数

conf -- [in] The config struct for the SSL connection.

返回

  • ESP_OK if adding certificates was successful.

  • Other if an error occurred or an action must be taken by the calling process.

void esp_crt_bundle_detach(mbedtls_ssl_config *conf)

Disable and dealloc the certification bundle.

Removes the certificate verification callback and deallocates used resources

参数

conf -- [in] The config struct for the SSL connection.

esp_err_t esp_crt_bundle_set(const uint8_t *x509_bundle, size_t bundle_size)

Set the default certificate bundle used for verification.

Overrides the default certificate bundle only in case of successful initialization. In most use cases the bundle should be set through menuconfig. The bundle needs to be sorted by subject name since binary search is used to find certificates.

参数

  • x509_bundle -- [in] A pointer to the certificate bundle.

  • bundle_size -- [in] Size of the certificate bundle in bytes.

返回

  • ESP_OK if adding certificates was successful.

  • Other if an error occurred or an action must be taken by the calling process.

bool esp_crt_bundle_in_use(const mbedtls_x509_crt *ca_chain)

Check if the given CA certificate chain is the default "dummy" certificate chain attached by the esp_crt_bundle.

参数

ca_chain -- A pointer to the CA chain.

返回

true if the ca_chain is the dummy CA chain attached by esp_crt_bundle

返回

false otherwise

提供有关此文档的反馈