docs: Provide Chinese translation for protocols/esp_crt_bundle.rst an…

…d mbedtls.rst
espressif · Sep 13, 2023 · e424fe0 · e424fe0
1 parent 90f3855
commit e424fe0
Show file tree

Hide file tree

Showing 5 changed files with 262 additions and 33 deletions.
diff --git a/docs/en/api-reference/protocols/esp_crt_bundle.rst b/docs/en/api-reference/protocols/esp_crt_bundle.rst
@@ -1,6 +1,8 @@
 ESP x509 Certificate Bundle
 ===========================
 
+:link_to_translation:`zh_CN:[中文]`
+
 Overview
 --------
 
@@ -10,7 +12,7 @@ The ESP x509 Certificate Bundle API provides an easy way to include a bundle of
 
     The bundle is currently not available when using WolfSSL.
 
-The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
+The bundle comes with the complete list of root certificates from Mozilla's NSS root certificate store. Using the gen_crt_bundle.py python utility, the certificates' subject name and public key are stored in a file and embedded in the {IDF_TARGET_NAME} binary.
 
 When generating the bundle you may choose between:
 
@@ -26,10 +28,10 @@ In addition, it is possible to specify a path to a certificate file or a directo
 Configuration
 -------------
 
-Most configuration is done through menuconfig. CMake will generate the bundle according to the configuration and embed it.
+Most configuration is done through menuconfig. CMake generates the bundle according to the configuration and embed it.
 
  * :ref:`CONFIG_MBEDTLS_CERTIFICATE_BUNDLE`: automatically build and attach the bundle.
- * :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root list.
+ * :ref:`CONFIG_MBEDTLS_DEFAULT_CERTIFICATE_BUNDLE`: decide which certificates to include from the complete root certificate list.
  * :ref:`CONFIG_MBEDTLS_CUSTOM_CERTIFICATE_BUNDLE_PATH`: specify the path of any additional certificates to embed in the bundle.
 
 To enable the bundle when using ESP-TLS simply pass the function pointer to the bundle attach function:
@@ -56,15 +58,16 @@ If using mbedTLS directly then the bundle may be activated by directly calling t
 
 Generating the List of Root Certificates
 ----------------------------------------
+
 The list of root certificates comes from Mozilla's NSS root certificate store, which can be found `here <https://wiki.mozilla.org/CA/Included_Certificates>`_
 
 The list can be downloaded and created by running the script ``mk-ca-bundle.pl`` that is distributed as a part of `curl <https://github.com/curl/curl>`_.
-Another alternative would be to download the finished list directly from the curl website: `CA certificates extracted from Mozilla <https://curl.se/docs/caextract.html>`_
 
-The common certificates bundle were made by selecting the authorities with a market share of more than 1 % from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
+Another alternative would be to download the finished list directly from the curl website: `CA certificates extracted from Mozilla <https://curl.se/docs/caextract.html>`_
 
-These authorities were then used to pick the names of the certificates for the filter list, `cmn_crt_authorities.csv`, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.
+The common certificates bundle were made by selecting the authorities with a market share of more than 1% from w3tech's `SSL Survey <https://w3techs.com/technologies/overview/ssl_certificate>`_.
 
+These authorities were then used to pick the names of the certificates for the filter list, ``cmn_crt_authorities.csv``, from `this list <https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReportPEMCSV>`_ provided by Mozilla.
 
 
 Updating the Certificate Bundle
@@ -73,9 +76,8 @@ Updating the Certificate Bundle
 The bundle is embedded into the app and can be updated along with the app by an OTA update. If you want to include a more up-to-date bundle than the bundle currently included in ESP-IDF, then the certificate list can be downloaded from Mozilla as described in :ref:`updating_bundle`.
 
 
-
-Application Example
--------------------
+Application Examples
+--------------------
 
 Simple HTTPS example that uses ESP-TLS to establish a secure socket connection using the certificate bundle with two custom certificates added for verification: :example:`protocols/https_x509_bundle`.
 
@@ -87,4 +89,3 @@ API Reference
 -------------
 
 .. include-build-file:: inc/esp_crt_bundle.inc
-
diff --git a/docs/en/api-reference/protocols/mbedtls.rst b/docs/en/api-reference/protocols/mbedtls.rst
@@ -1,6 +1,8 @@
 Mbed TLS
 ========
 
+:link_to_translation:`zh_CN:[中文]`
+
 `Mbed TLS <https://github.com/Mbed-TLS/mbedtls>`_ is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems.
 
 .. note::
@@ -16,6 +18,9 @@ Mbed TLS supports SSL 3.0 up to TLS 1.3 and DTLS 1.0 to 1.2 communication by pro
 - Hashing
 - Encryption/decryption
 
+Supported TLS versions include SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3, but on the latest ESP-IDF, SSL 3.0, TLS 1.0, and TLS 1.1 have been removed from Mbed TLS. Supported DTLS versions include DTLS 1.0, DTLS 1.1, and DTLS 1.2, but on the latest ESP-IDF, DTLS 1.0 has been removed from Mbed TLS.
+
+
 Mbed TLS Documentation
 ----------------------
 
@@ -27,12 +32,11 @@ For Mbed TLS documentation please refer to the following (upstream) pointers:
 Mbed TLS Support in ESP-IDF
 ---------------------------
 
-Please find the information about the Mbed TLS versions present in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
-
+Please find the information about the Mbed TLS versions presented in different branches of ESP-IDF `here <https://github.com/espressif/mbedtls/wiki#mbed-tls-support-in-esp-idf>`__.
 
 .. note::
 
-    Please refer the :ref:`ESP-IDF Migration Guide <migration_guide_mbedtls>` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
+    Please refer the :ref:`migration_guide_mbedtls` to migrate from Mbed TLS version 2.x to version 3.0 or greater.
 
 Application Examples
 --------------------
@@ -47,7 +51,7 @@ If the Mbed TLS API is to be used directly, refer to the example :example:`proto
 Alternatives
 ------------
 
-:doc:`/api-reference/protocols/esp_tls` acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at https://github.com/espressif/esp-wolfSSL with the upstream submodule pointer.
+:doc:`/api-reference/protocols/esp_tls` acts as an abstraction layer over the underlying SSL/TLS library and thus has an option to use Mbed TLS or wolfSSL as the underlying library. By default, only Mbed TLS is available and used in ESP-IDF whereas wolfSSL is available publicly at `<https://github.com/espressif/esp-wolfSSL>` with the upstream submodule pointer.
 
 Please refer to :ref:`ESP-TLS: Underlying SSL/TLS Library Options <esp_tls_wolfssl>` docs for more information on this and comparison of Mbed TLS and wolfSSL.
 
@@ -71,7 +75,7 @@ Following is a brief list of important config options accessible at ``Component
 
 .. note::
 
-    Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1 and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
+    Mbed TLS v3.0.0 and later support only TLS 1.2 and TLS 1.3 (SSL 3.0, TLS 1.0, TLS 1.1, and DTLS 1.0 are not supported). The support for TLS 1.3 is experimental and only supports the client-side. More information about this can be found out `here <https://github.com/espressif/mbedtls/blob/9bb5effc3298265f829878825d9bd38478e67514/docs/architecture/tls13-support.md>`__.
 
 
 Performance and Memory Tweaks
@@ -84,19 +88,28 @@ Reducing Heap Usage
 
 The following table shows typical memory usage with different configs when the :example:`protocols/https_request` example (with Server Validation enabled) was run with Mbed TLS as the SSL/TLS library.
 
-+------------------------------+--------------------------------------------------+----------------------+
-| Mbed TLS Test                | Related Configs                                  | Heap Usage (approx.) |
-+==============================+==================================================+======================+
-| Default                      | NA                                               | 42196 B              |
-+------------------------------+--------------------------------------------------+----------------------+
-| Enable SSL Variable Length   | :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH` | 42120 B              |
-+------------------------------+--------------------------------------------------+----------------------+
-| Disable Keep Peer Certificate| :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`  | 38533 B              |
-+------------------------------+--------------------------------------------------+----------------------+
-| Enable Dynamic TX/RX Buffer  | :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`             | 22013 B              |
-|                              | :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`   |                      |
-|                              | :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`       |                      |
-+------------------------------+--------------------------------------------------+----------------------+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 60 30
+    :align: center
+
+    * - Mbed TLS Test
+      - Related Configs
+      - Heap Usage (approx.)
+    * - Default
+      - NA
+      - 42196 B
+    * - Enable SSL Variable Length
+      - :ref:`CONFIG_MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH`
+      -  42120 B
+    * - Disable Keep Peer Certificate
+      - :ref:`CONFIG_MBEDTLS_SSL_KEEP_PEER_CERTIFICATE`
+      - 38533 B
+    * - Enable Dynamic TX/RX Buffer
+      - :ref:`CONFIG_MBEDTLS_DYNAMIC_BUFFER`
+        :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA`
+        :ref:`CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT`
+      - 22013 B
 
 .. note::
 
@@ -110,4 +123,4 @@ Under ``Component Config -> mbedTLS``, there are multiple Mbed TLS features whic
 
 
 .. _`API Reference`: https://mbed-tls.readthedocs.io/projects/api/en/v3.4.1/
-.. _`Knowledge Base`: https://mbed-tls.readthedocs.io/en/latest/kb/
+.. _`Knowledge Base`: https://mbed-tls.readthedocs.io/en/latest/kb/
diff --git a/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst b/docs/zh_CN/api-reference/protocols/esp_crt_bundle.rst
@@ -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
diff --git a/docs/zh_CN/api-reference/protocols/mbedtls.rst b/docs/zh_CN/api-reference/protocols/mbedtls.rst
@@ -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/