forked from espressif/esp-idf
docs: Update CN translation in protocols
This commit is contained in:
Zhang Shuxian
@@ -25,7 +25,7 @@ Simple HTTPS example that uses ESP-TLS to establish a secure socket connection:
|
||||
Tree Structure for ESP-TLS Component
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: none
|
||||
|
||||
├── esp_tls.c
|
||||
├── esp_tls.h
|
||||
@@ -55,7 +55,7 @@ ESP-TLS provides multiple options for TLS server verification on the client side
|
||||
|
||||
.. warning::
|
||||
|
||||
Enabling this option comes with a potential risk of establishing a TLS connection with a server that has a fake identity, provided that the server certificate is not provided either through API or other mechanisms like ca_store etc.
|
||||
If this option is enabled, there is a risk of establishing a TLS connection with a server that has a fake identity, unless the server certificate is provided through the API or other mechanisms like ``ca_store``.
|
||||
|
||||
ESP-TLS Server Cert Selection Hook
|
||||
----------------------------------
|
||||
@@ -92,22 +92,27 @@ How to Use WolfSSL with ESP-IDF
|
||||
|
||||
There are two ways to use WolfSSL in your project:
|
||||
|
||||
1) Directly add WolfSSL as a component in your project with the following three commands::
|
||||
- Add WolfSSL as a component directly to your project. For this, go to your project directory and run:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
(First, change the directory (cd) to your project directory)
|
||||
mkdir components
|
||||
cd components
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
2) Add WolfSSL as an extra component in your project.
|
||||
- Add WolfSSL as an extra component in your project.
|
||||
|
||||
* Download WolfSSL with::
|
||||
1. Download WolfSSL with:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
* Include ESP-WolfSSL in ESP-IDF with setting ``EXTRA_COMPONENT_DIRS`` in ``CMakeLists.txt`` of your project as done in `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_. For reference see :ref:`optional_project_variable` in :doc:`build-system.</api-guides/build-system>`.
|
||||
2. Include ESP-WolfSSL in ESP-IDF with setting ``EXTRA_COMPONENT_DIRS`` in ``CMakeLists.txt`` of your project as done in `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_. For reference see :ref:`optional_project_variable` in :doc:`build-system </api-guides/build-system>`.
|
||||
|
||||
After the above steps, you will have the option to choose WolfSSL as the underlying SSL/TLS library in the configuration menu of your project as follows::
|
||||
After the above steps, you will have the option to choose WolfSSL as the underlying SSL/TLS library in the configuration menu of your project as follow:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
idf.py menuconfig > ESP-TLS > SSL/TLS Library > Mbedtls/Wolfssl
|
||||
|
||||
@@ -151,19 +156,23 @@ To enable the secure element support, and use it in your project for TLS connect
|
||||
|
||||
1) Add `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_ in your project, for details please refer `how to use esp-cryptoauthlib with ESP-IDF <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_.
|
||||
|
||||
2) Enable the following menuconfig option::
|
||||
2) Enable the menuconfig option :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
|
||||
3) Select type of ATECC608A chip with following option::
|
||||
3) Select type of ATECC608A chip with following option:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > esp-cryptoauthlib > Choose Type of ATECC608A chip
|
||||
|
||||
To know more about different types of ATECC608A chips and how to obtain the type of ATECC608A connected to your ESP module, please visit `ATECC608A chip type <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_.
|
||||
To know more about different types of ATECC608A chips and how to obtain the type of ATECC608A connected to your ESP module, please visit `ATECC608A chip type <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_.
|
||||
|
||||
4) Enable the use of ATECC608A in ESP-TLS by providing the following config option in :cpp:type:`esp_tls_cfg_t`.
|
||||
4) Enable the use of ATECC608A in ESP-TLS by providing the following config option in :cpp:type:`esp_tls_cfg_t`:
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
esp_tls_cfg_t cfg = {
|
||||
/* other configurations options */
|
||||
@@ -226,7 +235,7 @@ To know more about different types of ATECC608A chips and how to obtain the type
|
||||
|
||||
|
||||
TLS Ciphersuites
|
||||
------------------------------------
|
||||
----------------
|
||||
|
||||
ESP-TLS provides the ability to set a ciphersuites list in client mode. The TLS ciphersuites list informs the server about the supported ciphersuites for the specific TLS connection regardless of the TLS stack configuration. If the server supports any ciphersuite from this list, then the TLS connection will succeed; otherwise, it will fail.
|
||||
|
||||
@@ -259,7 +268,7 @@ To set TLS protocol version with ESP-TLS, set :cpp:member:`esp_tls_cfg_t::tls_ve
|
||||
|
||||
The ESP-TLS connection can be configured to use the specified protocol version as follows:
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_tls.h"
|
||||
esp_tls_cfg_t cfg = {
|
||||
|
||||
@@ -42,11 +42,11 @@ Application Examples
|
||||
MQTT Message Retransmission
|
||||
---------------------------
|
||||
|
||||
A new MQTT message is created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
|
||||
A new MQTT message can be created by calling :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish()>` or its non-blocking counterpart :cpp:func:`esp_mqtt_client_enqueue <esp_mqtt_client_enqueue()>`.
|
||||
|
||||
Messages with QoS 0 is sent only once. QoS 1 and 2 have different behaviors since the protocol requires extra steps to complete the process.
|
||||
Messages with QoS 0 are sent only once. QoS 1 and 2 behave differently since the protocol requires additional steps to complete the process.
|
||||
|
||||
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to avoid losses in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
|
||||
The ESP-MQTT library opts to always retransmit unacknowledged QoS 1 and 2 publish messages to prevent data loss in faulty connections, even though the MQTT specification requires the re-transmission only on reconnect with Clean Session flag been set to 0 (set :cpp:member:`disable_clean_session <esp_mqtt_client_config_t::session_t::disable_clean_session>` to true for this behavior).
|
||||
|
||||
QoS 1 and 2 messages that may need retransmission are always enqueued, but first transmission try occurs immediately if :cpp:func:`esp_mqtt_client_publish <esp_mqtt_client_publish>` is used. A transmission retry for unacknowledged messages will occur after :cpp:member:`message_retransmit_timeout <esp_mqtt_client_config_t::session_t::message_retransmit_timeout>`. After :ref:`CONFIG_MQTT_OUTBOX_EXPIRED_TIMEOUT_MS` messages will expire and be deleted. If :ref:`CONFIG_MQTT_REPORT_DELETED_MESSAGES` is set, an event will be sent to notify the user.
|
||||
|
||||
|
||||
@@ -32,14 +32,12 @@ HTTP 基本请求
|
||||
|
||||
为了使 ESP HTTP 客户端充分利用持久连接的优势，建议尽可能多地使用同一个句柄实例来发起请求，可参考应用示例中的函数 ``http_rest_with_url`` 和 ``http_rest_with_hostname_path``。示例中，一旦创建连接，即会在连接关闭前发出多个请求（如 ``GET``、 ``POST``、 ``PUT`` 等）。
|
||||
|
||||
.. only:: esp32
|
||||
为 TLS 使用安全元件 (ATECC608)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
为 TLS 使用安全元件 (ATECC608)
|
||||
__________________________________
|
||||
安全元件 (ATECC608) 也可用于 HTTP 客户端连接中的底层 TLS 连接。详细内容请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 **ESP-TLS 中的 ATECC608A（安全元件）支持** 小节。如需支持安全元素，必须首先在 menuconfig 中通过 :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT` 对其进行启用，此后，可配置 HTTP 客户端使用安全元素，如下所示：
|
||||
|
||||
安全元件 (ATECC608) 也可用于 HTTP 客户端连接中的底层 TLS 连接。请参考 :doc:`ESP-TLS 文档 </api-reference/protocols/esp_tls>` 中的 *ESP-TLS 中的 ATECC608A（安全元件）支持* 小节，了解更多细节。如需支持安全元素，必须首先在 menuconfig 中通过 :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT` 对其进行启用，此后，可配置 HTTP 客户端使用安全元素，如下所示：
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
esp_http_client_config_t cfg = {
|
||||
/* other configurations options */
|
||||
|
||||
@@ -25,7 +25,7 @@ ESP-TLS 组件提供简化 API 接口，用于访问常用 TLS 功能，支持
|
||||
ESP-TLS 组件的树形结构
|
||||
-------------------------------------
|
||||
|
||||
.. code-block:: none
|
||||
.. code-block:: none
|
||||
|
||||
├── esp_tls.c
|
||||
├── esp_tls.h
|
||||
@@ -79,7 +79,7 @@ ESP-TLS 服务器证书选择回调
|
||||
.. _esp_tls_wolfssl:
|
||||
|
||||
底层 SSL/TLS 库选择
|
||||
----------------------------------
|
||||
-------------------------
|
||||
|
||||
ESP-TLS 组件支持以 MbedTLS 或 WolfSSL 作为其底层 SSL/TLS 库，默认仅使用 MbedTLS，WolfSSL 的 SSL/TLS 库可在 https://github.com/espressif/esp-wolfssl 上公开获取，该仓库提供二进制格式的 WolfSSL 组件，并提供了一些示例帮助用户了解相关 API。有关许可证和其他选项，请参阅仓库的 ``README.md`` 文件。下文介绍了在工程中使用 WolfSSL 的具体流程。
|
||||
|
||||
@@ -92,22 +92,27 @@ ESP-TLS 组件支持以 MbedTLS 或 WolfSSL 作为其底层 SSL/TLS 库，默认
|
||||
|
||||
要在工程中使用 WolfSSL，可采取以下两种方式：
|
||||
|
||||
1) 使用以下三行命令，将 WolfSSL 作为组件直接添加到工程中::
|
||||
- 将 WolfSSL 作为组件直接添加到工程中。用 cd 命令进入工程目录后，使用以下命令：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
（首先用 cd 命令进入工程目录）
|
||||
mkdir components
|
||||
cd components
|
||||
git clone https://github.com/espressif/esp-wolfssl.git
|
||||
git clone --recursive https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
2) 将 WolfSSL 作为额外组件添加到工程中。
|
||||
- 将 WolfSSL 作为额外组件添加到工程中。
|
||||
|
||||
* 使用以下命令下载 WolfSSL::
|
||||
1. 使用以下命令下载 WolfSSL：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
git clone https://github.com/espressif/esp-wolfssl.git
|
||||
|
||||
* 参照 `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_ 示例，在工程的 ``CMakeLists.txt`` 文件中设置 ``EXTRA_COMPONENT_DIRS``，从而在 ESP-IDF 中包含 ESP-WolfSSL，详情请参阅 :doc:`构建系统 </api-guides/build-system>` 中的 :ref:`optional_project_variable` 小节。
|
||||
2. 参照 `wolfssl/examples <https://github.com/espressif/esp-wolfssl/tree/master/examples>`_ 示例，在工程的 ``CMakeLists.txt`` 文件中设置 ``EXTRA_COMPONENT_DIRS``，从而在 ESP-IDF 中包含 ESP-WolfSSL，详情请参阅 :doc:`构建系统 </api-guides/build-system>` 中的 :ref:`optional_project_variable` 小节。
|
||||
|
||||
完成上述步骤后，可以在工程配置菜单中将 WolfSSL 作为底层 SSL/TLS 库，具体步骤如下::
|
||||
完成上述步骤后，可以在工程配置菜单中将 WolfSSL 作为底层 SSL/TLS 库，具体步骤如下：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
idf.py menuconfig > ESP-TLS > SSL/TLS Library > Mbedtls/Wolfssl
|
||||
|
||||
@@ -138,32 +143,34 @@ MbedTLS 与 WolfSSL 对比
|
||||
|
||||
若配置选项不同或相应库的版本不同，得到的值可能与上表不同。
|
||||
|
||||
.. only:: esp32
|
||||
ESP-TLS 中的 ATECC608A（安全元件）
|
||||
-----------------------------------------
|
||||
|
||||
ESP-TLS 中的 ATECC608A（安全元件）
|
||||
--------------------------------------------------
|
||||
ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须将 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈。未经手动更改，ESP-TLS 默认以 MbedTLS 为其底层 TLS/SSL 协议栈。
|
||||
|
||||
ESP-TLS 支持在 ESP32 系列芯片上使用 ATECC608A 加密芯片，但必须将 MbedTLS 作为 ESP-TLS 的底层 SSL/TLS 协议栈。未经手动更改，ESP-TLS 默认以 MbedTLS 为其底层 TLS/SSL 协议栈。
|
||||
.. note::
|
||||
|
||||
.. note::
|
||||
在 ESP32 系列上的 ATECC608A 芯片必须预先配置，详情请参阅 `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_。
|
||||
|
||||
在 ESP32 上的 ATECC608A 芯片必须预先配置，详情请参阅 `esp_cryptoauth_utility <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#esp_cryptoauth_utility>`_。
|
||||
要启用安全元件支持，并将其应用于工程 TLS 连接，请遵循以下步骤：
|
||||
|
||||
要启用安全元件支持，并将其应用于工程 TLS 连接，请遵循以下步骤：
|
||||
1) 在工程中添加 `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_，详情请参阅 `如何在 ESP-IDF 中使用 esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_。
|
||||
|
||||
1) 在工程中添加 `esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib>`_，详情请参阅 `如何在 ESP-IDF 中使用 esp-cryptoauthlib <https://github.com/espressif/esp-cryptoauthlib#how-to-use-esp-cryptoauthlib-with-esp-idf>`_。
|
||||
2) 启用 menuconfig 选项 :ref:`CONFIG_ESP_TLS_USE_SECURE_ELEMENT`：
|
||||
|
||||
2) 启用以下 menuconfig 选项::
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > ESP-TLS > Use Secure Element (ATECC608A) with ESP-TLS
|
||||
|
||||
3) 选择 ATECC608A 芯片类型::
|
||||
3) 选择 ATECC608A 芯片类型：
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
menuconfig > Component config > esp-cryptoauthlib > Choose Type of ATECC608A chip
|
||||
|
||||
如需了解更多 ATECC608A 芯片类型，或需了解如何获取连接到特定 ESP 模块的 ATECC608A 芯片类型，请参阅 `ATECC608A 芯片类型 <https://github.com/espressif/esp-cryptoauthlib/blob/master/esp_cryptoauth_utility/README.md#find-type-of-atecc608a-chip-connected-to-esp32-wroom32-se>`_。
|
||||
|
||||
4) 在 :cpp:type:`esp_tls_cfg_t` 中提供以下配置，在 ESP-TLS 中启用 ATECC608A。
|
||||
4) 在 :cpp:type:`esp_tls_cfg_t` 中提供以下配置，在 ESP-TLS 中启用 ATECC608A：
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -228,7 +235,7 @@ MbedTLS 与 WolfSSL 对比
|
||||
|
||||
|
||||
TLS 加密套件
|
||||
------------------------------------
|
||||
----------------
|
||||
|
||||
ESP-TLS 支持在客户端模式下设置加密套件列表，TLS 密码套件列表用于向服务器传递所支持的密码套件信息，用户可以根据自己需求增减加密套件，且适用于任何 TLS 协议栈配置。如果服务器支持列表中的任一密码套件，则 TLS 连接成功，反之连接失败。
|
||||
|
||||
@@ -261,7 +268,7 @@ ESP-TLS 能够为 TLS 连接设置相应的 TLS 协议版本，指定版本将
|
||||
|
||||
ESP-TLS 连接的协议版本可按如下方式配置：
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
#include "esp_tls.h"
|
||||
esp_tls_cfg_t cfg = {
|
||||
|
||||
@@ -154,7 +154,7 @@ ESP-MQTT 库将始终重新传输未确认的 QoS 1 和 2 发布消息，以避
|
||||
|
||||
* :cpp:member:`password <esp_mqtt_client_config_t::credentials_t::authentication_t::password>`：使用密码
|
||||
* * :cpp:member:`certificate <esp_mqtt_client_config_t::credentials_t::authentication_t::certificate>` 和 :cpp:member:`key <esp_mqtt_client_config_t::credentials_t::authentication_t::key>`：进行双向 TLS 身份验证，PEM 或 DER 格式均可
|
||||
* :cpp:member:`use_secure_element <esp_mqtt_client_config_t::credentials_t::authentication_t::use_secure_element>`：使用 ESP32 中的安全元素 (ATECC608A)
|
||||
* :cpp:member:`use_secure_element <esp_mqtt_client_config_t::credentials_t::authentication_t::use_secure_element>`：使用 ESP32 系列中的安全元素 (ATECC608A)
|
||||
* :cpp:member:`ds_data <esp_mqtt_client_config_t::credentials_t::authentication_t::ds_data>`：使用某些乐鑫设备的数字签名外设
|
||||
|
||||
会话
|
||||
|
||||
Reference in New Issue
Block a user