-
Notifications
You must be signed in to change notification settings - Fork 7.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'docs/add_CN_trans_for_protocols/esp_crt_bundle_and_mbed…
…tls.rst' into 'master' docs: Provide Chinese translation for protocols/esp_crt_bundle.rst and mbedtls.rst Closes DOC-5999 See merge request espressif/esp-idf!25357
- Loading branch information
Showing
5 changed files
with
262 additions
and
33 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,91 @@ | ||
| .. include:: ../../../en/api-reference/protocols/esp_crt_bundle.rst | ||
| ESP x509 证书包 | ||
| =================== | ||
|
|
||
| :link_to_translation:`en:[English]` | ||
|
|
||
| 概述 | ||
| ----- | ||
|
|
||
| ESP x509 证书包 API 提供了一种简便的方法，帮助你安装自定义 x509 根证书用于 TLS 服务器验证。 | ||
|
|
||
| .. note:: | ||
|
|
||
| 目前在使用 WolfSSL 时该证书包不可用。 | ||
|
|
||
| 该证书包中包括 Mozilla NSS 根证书存储区的完整根证书列表。使用 gen_crt_bundle.py python 程序，可将证书的主题名称和公钥存储在文件中，并嵌入 {IDF_TARGET_NAME} 二进制文件。 | ||
|
|
||
| 生成证书包时，你需选择： | ||
|
|
||
| * 来自 Mozilla 的完整根证书包，包含超过 130 份证书。目前提供的证书包更新于 2023 年 1 月 10 日，星期二，04:12:06 (GMT)。 | ||
| * 一组预先筛选的常用根证书。其中仅包含约 41 份证书，但根据 SSL 证书颁发机构统计数据，其绝对使用率约达到 90%，市场覆盖率约达 99%。 | ||
|
|
||
| 此外，还可指定证书文件的路径或包含证书的目录，将其他证书添加到生成的证书包中。 | ||
|
|
||
| .. note:: | ||
|
|
||
| 信任所有根证书意味着如果任何证书被收回，就必须更新证书列表，包括从 ``cacrt_all.pem`` 中将其删除。 | ||
|
|
||
| 配置 | ||
| ------ | ||
|
|
||
| 多数配置可通过 menuconfig 完成。CMake 会根据配置信息生成及嵌入证书包。 | ||
|
|
||
| * :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`：自动创建并附加证书包。 | ||
| * :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`：决定添加证书列表中的哪些证书。 | ||
| * :ref:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`：指定要在证书包中嵌入的其他证书的路径。 | ||
|
|
||
| 要在使用 ESP-TLS 时启用证书包，将函数指针指向证书包的 attach 函数： | ||
|
|
||
| .. code-block:: c | ||
| esp_tls_cfg_t cfg = { | ||
| .crt_bundle_attach = esp_crt_bundle_attach, | ||
| }; | ||
| 此步骤是为了避免在用户未使能的情况下嵌入证书包。 | ||
|
|
||
| 如果直接使用 mbedTLS 包，在设置阶段直接调用 attach 函数可以激活证书包： | ||
|
|
||
| .. code-block:: c | ||
| mbedtls_ssl_config conf; | ||
| mbedtls_ssl_config_init(&conf); | ||
| esp_crt_bundle_attach(&conf); | ||
| .. _updating_bundle: | ||
|
|
||
| 生成根证书列表 | ||
| ---------------- | ||
|
|
||
| 根证书列表来自 Mozilla 的 `NSS 根证书商店 <https://wiki.mozilla.org/CA/Included_Certificates>`_。 | ||
|
|
||
| 运行 ``mk-ca-bundle.pl`` 脚本可下载和创建列表。脚本发布于 `curl <https://github.com/curl/curl>`_。 | ||
|
|
||
| 还可通过 curl 网站直接下载完整列表： `从 Mozilla 提取的 CA 证书 <https://curl.se/docs/caextract.html>`_。 | ||
|
|
||
| 常用证书包是通过筛选出市场份额超过 1% 的授权机构来决定的，筛选数据来自 w3tech 的 `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_。 | ||
|
|
||
| 根据这些授权机构，从 Mozilla 提供的 `列表 <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ 的 ``cmn_crt_authorities.csv`` 中筛选证书名称。 | ||
|
|
||
|
|
||
| 更新证书包 | ||
| ------------ | ||
|
|
||
| 证书包嵌入到应用程序中，通过 OTA 更新与应用程序一起更新。如果想使用比目前 ESP-IDF 中的证书包更新的包，则可按照 :ref:`updating_bundle` 中的说明从 Mozilla 下载证书列表。 | ||
|
|
||
|
|
||
| 应用示例 | ||
| --------- | ||
|
|
||
| 使用 ESP-TLS 创建安全套接字连接的简单 HTTPS 示例：:example:`protocols/https_x509_bundle`，该示例使用了证书包并添加了两个自定义证书用于验证。 | ||
|
|
||
| 使用 ESP-TLS 和默认证书包的 HTTPS 示例：:example:`protocols/https_request`。 | ||
|
|
||
| 使用 mbedTLS 和默认证书包的 HTTPS 示例：:example:`protocols/https_mbedtls`。 | ||
|
|
||
| API 参考 | ||
| ---------- | ||
|
|
||
| .. include-build-file:: inc/esp_crt_bundle.inc |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,126 @@ | ||
| .. include:: ../../../en/api-reference/protocols/mbedtls.rst | ||
| Mbed TLS | ||
| ======== | ||
|
|
||
| :link_to_translation:`en:[English]` | ||
|
|
||
| `Mbed TLS <https://github.com/Mbed-TLS/mbedtls>`_ 是一个 C 代码库，用于实现加密基元、X.509 证书操作以及 SSL/TLS 和 DTLS 协议。该库代码占用空间小，适合嵌入式系统使用。 | ||
|
|
||
| .. note:: | ||
|
|
||
| ESP-IDF 使用的 Mbed TLS `复刻仓库 <https://github.com/espressif/mbedtls>`_ 中包含对原生 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 文档请参阅以下（上游）指针： | ||
|
|
||
| - `API Reference`_ | ||
| - `Knowledge Base`_ | ||
|
|
||
| ESP-IDF 的 Mbed TLS 支持 | ||
| ------------------------------ | ||
|
|
||
| 请在 `此处 <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__ 查找 ESP-IDF 不同分支上的 Mbed TLS 版本信息。 | ||
|
|
||
| .. note:: | ||
|
|
||
| 参考 :ref:`migration_guide_mbedtls` 从 Mbed TLS 2.x 版本迁移到 3.0 及以上版本。 | ||
|
|
||
| 应用示例 | ||
| ------------- | ||
|
|
||
| ESP-IDF 中的示例使用 :doc:`/api-reference/protocols/esp_tls`，为访问常用的 TLS 功能提供了一个简化 API 接口。 | ||
|
|
||
| 参考示例 :example:`protocols/https_server/simple` （简单的 HTTPS 服务器）和 :example:`protocols/https_request` （发出 HTTPS 请求）了解更多信息。 | ||
|
|
||
| 如需直接使用 Mbed TLS API，请参考示例 :example:`protocols/https_mbedtls`。 | ||
|
|
||
|
|
||
| 其他选项 | ||
| ---------- | ||
|
|
||
| :doc:`/api-reference/protocols/esp_tls` 是底层 SSL/TLS 库的抽象层，因此可以选择使用 Mbed TLS 或 wolfSSL 作为底层库。默认情况下，仅 Mbed TLS 可在 ESP-IDF 中使用，而 wolfSSL 在 `<https://github.com/espressif/esp-wolfSSL>`_ 公开，还提供了上游子模块指针的相关信息。 | ||
|
|
||
| 如需了解更多相关信息或比较 Mbed TLS 和 wolfSSL，请参考文档 :ref:`ESP-TLS: Underlying SSL/TLS Library Options <esp_tls_wolfssl>`。 | ||
|
|
||
|
|
||
| 重要配置 | ||
| ------------- | ||
|
|
||
| ``Component Config -> mbedTLS`` 中的部分重要配置选项如下表所示。点击 :ref:`此处 <CONFIG_MBEDTLS_MEM_ALLOC_MODE>` 获取完整配置选项列表。 | ||
|
|
||
| .. list:: | ||
|
|
||
| - :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_2`: 支持 TLS 1.2 | ||
| - :ref:`CONFIG_MBEDTLS_SSL_PROTO_TLS1_3`: 支持 TLS 1.3 | ||
| - :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: 支持受信任的根证书包（更多信息请参考 :doc:`/api-reference/protocols/esp_crt_bundle`） | ||
| - :ref:`CONFIG_MBEDTLS_CLIENT_SSL_SESSION_TICKETS`: 支持 TLS 会话恢复：客户端会话票证 | ||
| - :ref:`CONFIG_MBEDTLS_SERVER_SSL_SESSION_TICKETS`: 支持 TLS 会话恢复：服务会话票证 | ||
| - :ref:`CONFIG_MBEDTLS_HARDWARE_SHA`: 支持硬件 SHA 加速 | ||
| :SOC_AES_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_AES`: 支持硬件 AES 加速 | ||
| :SOC_MPI_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_MPI`: 支持硬件 MPI (bignum) 加速 | ||
| :SOC_ECC_SUPPORTED: - :ref:`CONFIG_MBEDTLS_HARDWARE_ECC`: 支持硬件 ECC 加速 | ||
|
|
||
| .. note:: | ||
|
|
||
| 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 尚在试验阶段，仅支持客户端。要了解更多信息，请点击 `此处 <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__。 | ||
|
|
||
|
|
||
| 性能和内存调整 | ||
| ------------------ | ||
|
|
||
| .. _reducing_ram_usage_mbedtls: | ||
|
|
||
| 减少内存使用 | ||
| ^^^^^^^^^^^^^^^^^ | ||
|
|
||
| 下表展示了在不同配置下，用 Mbed TLS 作为 SSL/TLS 库运行示例 :example:`protocols/https_request` （启用服务器验证）时，内存的实际使用情况。 | ||
|
|
||
| .. list-table:: | ||
| :header-rows: 1 | ||
| :widths: 25 60 30 | ||
| :align: center | ||
|
|
||
| * - 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 | ||
| * - 启用动态 buffer 功能 | ||
| - :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER` | ||
| :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA` | ||
| :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT` | ||
| - 22013 B | ||
|
|
||
| .. note:: | ||
|
|
||
| 这些值会随着配置选项和 Mbed TLS 版本的变化而变化。 | ||
|
|
||
|
|
||
| 减小固件大小 | ||
| ^^^^^^^^^^^^^^^^^^^^ | ||
|
|
||
| 在 ``Component Config -> mbedTLS`` 中，有多个 Mbed TLS 功能默认为启用状态。如果不需要这些功能，可将其禁用以减小固件大小。要了解更多信息，请参考 :ref:`Minimizing Binary Size <minimizing_binary_mbedtls>` 文档。 | ||
|
|
||
|
|
||
| .. _`API Reference`: https://mbed-tls.readthedocs.io/projects/api/en/v3.4.1/ | ||
| .. _`Knowledge Base`: https://mbed-tls.readthedocs.io/en/latest/kb/ |
Oops, something went wrong.