From 7df991f8416ca93ee45d8831894787507ad4abef Mon Sep 17 00:00:00 2001 From: Shang Zhou Date: Wed, 7 Sep 2022 16:06:31 +0800 Subject: [PATCH] docs: provide translation for protocols in migration guides --- .../release-5.x/protocols.rst | 75 +++---- .../release-5.x/protocols.rst | 206 +++++++++++++++++- 2 files changed, 243 insertions(+), 38 deletions(-) diff --git a/docs/en/migration-guides/release-5.x/protocols.rst b/docs/en/migration-guides/release-5.x/protocols.rst index 30158dad67..842ee4e8b6 100644 --- a/docs/en/migration-guides/release-5.x/protocols.rst +++ b/docs/en/migration-guides/release-5.x/protocols.rst @@ -1,6 +1,8 @@ Protocols ========= +:link_to_translation:`zh_CN:[中文]` + .. _migration_guide_mbedtls: Mbed TLS @@ -8,7 +10,7 @@ Mbed TLS For ESP-IDF v5.0, `Mbed TLS `_ has been updated from v2.x to v3.1.0. -The official guide for Mbed TLS to migrate from version 2.x to version 3.0 or greater can be found `here `__. +For more details about Mbed TLS's migration from version 2.x to version 3.0 or greater, please refer to the `official guide `__. Breaking Changes (Summary) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -18,19 +20,19 @@ Most structure fields are now private - Direct access to fields of structures (``struct`` types) declared in public headers is no longer supported. - Appropriate accessor functions (getter/setter) must be used for the same. A temporary workaround would be to use ``MBEDTLS_PRIVATE`` macro (**not recommended**). -- For more details, refer to the official guide `here `__. +- For more details, refer to the `official guide `__. SSL ^^^ -- Removed support for TLS 1.0, 1.1 and DTLS 1.0 +- Removed support for TLS 1.0, 1.1, and DTLS 1.0 - Removed support for SSL 3.0 -Deprecated functions were removed from cryptography modules +Deprecated Functions Were Removed from Cryptography Modules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - The functions ``mbedtls_*_ret()`` (related to MD, SHA, RIPEMD, RNG, HMAC modules) was renamed to replace the corresponding functions without ``_ret`` appended and updated return value. -- For more details, refer to the official guide `here `__. +- For more details, refer to the `official guide `__. Deprecated Config Options @@ -44,13 +46,13 @@ Following are some of the important config options deprecated by this update. Th - ``MBEDTLS_DES_C`` : Support for 3DES ciphersuites - ``MBEDTLS_RC4_MODE`` : Support for RC4-based ciphersuites -.. note:: This list includes only major options configurable through ``idf.py menuconfig``. For more details on deprecated options, refer to the official migration guide. +.. note:: This list includes only major options configurable through ``idf.py menuconfig``. For more details on deprecated options, refer to the `official guide `__. Miscellaneous ------------- -Disabled Diffie-Hellman Key Exchange modes +Disabled Diffie-Hellman Key Exchange Modes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The Diffie-Hellman Key Exchange modes have now been disabled by default due to security risks (see warning text `here `__). Related configs are given below: @@ -61,17 +63,17 @@ The Diffie-Hellman Key Exchange modes have now been disabled by default due to s .. note:: During the initial step of the handshake (i.e. ``client_hello``), the server selects a cipher from the list that the client publishes. As the DHE_PSK/DHE_RSA ciphers have now been disabled by the above change, the server would fall back to an alternative cipher; if in a rare case, it does not support any other cipher, the handshake would fail. To retrieve the list of ciphers supported by the server, one must attempt to connect with the server with a specific cipher from the client-side. Few utilities can help do this, e.g. ``sslscan``. -Remove ``certs`` module from X509 library +Remove ``certs`` Module from X509 Library ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The ``mbedtls/certs.h`` header is no longer available in mbedtls 3.1, most applications can safely remove it from the list of includes. +- The ``mbedtls/certs.h`` header is no longer available in mbedtls 3.1. Most applications can safely remove it from the list of includes. -Breaking change for ``esp_crt_bundle_set`` API +Breaking Change for ``esp_crt_bundle_set`` API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The :cpp:func:`esp_crt_bundle_set()` API now requires one additional argument named ``bundle_size``. The return type of the API has also been changed to :cpp:type:`esp_err_t` from ``void``. -Breaking change for ``esp_ds_rsa_sign`` API +Breaking Change for ``esp_ds_rsa_sign`` API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The :cpp:func:`esp_ds_rsa_sign()` API now requires one less argument. The argument ``mode`` is no longer required. @@ -85,10 +87,10 @@ Breaking Changes (Summary) Names of variables holding different certs in :cpp:type:`httpd_ssl_config_t` structure have been updated. .. list:: - * :cpp:member:`httpd_ssl_config::servercert` variable inherits role of `cacert_pem` variable. - * :cpp:member:`httpd_ssl_config::servercert_len` variable inherits role of `cacert_len` variable - * :cpp:member:`httpd_ssl_config::cacert_pem` variable inherits role of `client_verify_cert_pem` variable - * :cpp:member:`httpd_ssl_config::cacert_len` variable inherits role of `client_verify_cert_len` variable + * :cpp:member:`httpd_ssl_config::servercert` variable inherits role of ``cacert_pem`` variable. + * :cpp:member:`httpd_ssl_config::servercert_len` variable inherits role of ``cacert_len`` variable + * :cpp:member:`httpd_ssl_config::cacert_pem` variable inherits role of ``client_verify_cert_pem`` variable + * :cpp:member:`httpd_ssl_config::cacert_len` variable inherits role of ``client_verify_cert_len`` variable The return type of the :cpp:func:`httpd_ssl_stop` API has been changed to :cpp:type:`esp_err_t` from ``void``. @@ -107,30 +109,33 @@ ESP-TLS Breaking Changes (Summary) ~~~~~~~~~~~~~~~~~~~~~~~~~~ -``esp_tls_t`` structure is now private +``esp_tls_t`` Structure is Now Private ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :cpp:type:`esp_tls_t` has now been made completely private. You cannot access its internal structures directly. Any necessary data that needs to be obtained from the esp-tls handle can be done through respective getter/setter functions. If there is a requirement of a specific getter/setter function please raise an issue on ESP-IDF. +The :cpp:type:`esp_tls_t` has now been made completely private. You cannot access its internal structures directly. Any necessary data that needs to be obtained from the ESP-TLS handle can be done through respective getter/setter functions. If there is a requirement of a specific getter/setter function, please raise an `issue `__ on ESP-IDF. The list of newly added getter/setter function is as as follows: .. list:: - * :cpp:func:`esp_tls_get_ssl_context` - Obtain the ssl context of the underlying ssl stack from the esp-tls handle. + * :cpp:func:`esp_tls_get_ssl_context` - Obtain the ssl context of the underlying ssl stack from the ESP-TLS handle. -Function deprecations and recommended alternatives +Function Deprecations And Recommended Alternatives ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Following table summarizes the deprecated functions removed and their alternatives to be used from ESP-IDF v5.0 onwards. -+-----------------------------------+----------------------------------------+ -| Function | Alternative | -+===================================+========================================+ -| :cpp:func:`esp_tls_conn_new` | :cpp:func:`esp_tls_conn_new_sync` | -+-----------------------------------+----------------------------------------+ -| :cpp:func:`esp_tls_conn_delete` | :cpp:func:`esp_tls_conn_destroy` | -+-----------------------------------+----------------------------------------+ +.. list-table:: + :widths: 50 50 + :header-rows: 1 -- The function :cpp:func:`esp_tls_conn_http_new` has now been termed as deprecated. Please use the alternative function :cpp:func:`esp_tls_conn_http_new_sync` (or its asynchronous :cpp:func:`esp_tls_conn_http_new_async`). Note that the alternatives need an additional parameter :cpp:type:`esp_tls_t` which has to be initialized using the :cpp:func:`esp_tls_init` function. + * - Deprecated Function + - Alternative + * - ``esp_tls_conn_new()`` + - :cpp:func:`esp_tls_conn_new_sync` + * - ``esp_tls_conn_delete()`` + - :cpp:func:`esp_tls_conn_destroy` + +- The function :cpp:func:`esp_tls_conn_http_new` has now been termed as deprecated. Please use the alternative function :cpp:func:`esp_tls_conn_http_new_sync` (or its asynchronous :cpp:func:`esp_tls_conn_http_new_async`). Note that the alternatives need an additional parameter :cpp:type:`esp_tls_t`, which has to be initialized using the :cpp:func:`esp_tls_init` function. HTTP Server ----------- @@ -179,15 +184,13 @@ ESP-Modbus Breaking Changes (Summary) ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ESP-IDF component ``freemodbus`` has been removed from ESP-IDF and will be supported as a separate component. Additional information for the ``ESP-Modbus`` component can be found in the separate repository: +The ESP-IDF component ``freemodbus`` has been removed from ESP-IDF and is supported as a separate component. Additional information for the ``ESP-Modbus`` component can be found in the separate repository: * `ESP-Modbus component on GitHub `__ -The ``main`` component folder of the new application shall include the component manager manifest file ``idf_component.yml`` as in example below: +The ``main`` component folder of the new application shall include the component manager manifest file ``idf_component.yml`` as in the example below: -.. highlight:: none - -:: +.. code-block:: text dependencies: espressif/esp-modbus: @@ -195,10 +198,8 @@ The ``main`` component folder of the new application shall include the component The ``esp-modbus`` component can be found in `component manager registry `__. Refer to `component manager documentation `__ for more information on how to set up the component manager. -Applications targeting v4.x releases of ESP-IDF which use the new ``esp-modbus`` component should exclude the legacy ``freemodbus`` component from the build. This can be achieved using the below statement in project ``CMakeLists.txt``: +For applications targeting v4.x releases of ESP-IDF that need to use new ``esp-modbus`` component, adding the component manager manifest file ``idf_component.yml`` will be sufficient to pull in the new component. However, users should also exclude the legacy ``freemodbus`` component from the build. This can be achieved using the statement below in the project's ``CMakeLists.txt``: -.. highlight:: none +.. code-block:: cmake -:: - - set(EXCLUDE_COMPONENTS freemodbus) \ No newline at end of file + set(EXCLUDE_COMPONENTS freemodbus) diff --git a/docs/zh_CN/migration-guides/release-5.x/protocols.rst b/docs/zh_CN/migration-guides/release-5.x/protocols.rst index 47b0509019..87bcec3621 100644 --- a/docs/zh_CN/migration-guides/release-5.x/protocols.rst +++ b/docs/zh_CN/migration-guides/release-5.x/protocols.rst @@ -1 +1,205 @@ -.. include:: ../../../en/migration-guides/release-5.x/protocols.rst +协议 +========= + +:link_to_translation:`en:[English]` + +.. _migration_guide_mbedtls: + +Mbed TLS +-------- + +在 ESP-IDF v5.0 版本中，`Mbed TLS `_ 已从 v2.x 版本更新到 v3.1.0 版本。 + +更多有关 Mbed TLS 从 v2.x 版本迁移到 v3.0 或更高版本的详细信息，请参考 `官方指南 `__。 + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~ + +增加私有结构体字段数量 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- 不再支持直接访问公共头文件中声明的结构体（ ``struct`` 类型）字段。 +- 当前版本下，访问公共头文件中声明的结构体字段需要使用特定的访问函数 (getter/setter)。另外，也可以用 ``MBEDTLS_PRIVATE`` 宏暂时代替，但不建议使用此种方法。 +- 更多详细信息，请参考 `官方指南 `__。 + + +SSL +^^^ +- 不再支持 TLS 1.0、TLS 1.1 和 DTLS 1.0 +- 不再支持 SSL 3.0 + +移除密码模块中的废弃函数 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- 更新了与 MD、SHA、RIPEMD、RNG、HMAC 模块相关的函数 ``mbedtls_*_ret()`` 的返回值，并将其重新命名，以取代未附加 ``_ret`` 的相应函数。 +- 更多详细信息，请参考 `官方指南 `__。 + + +废弃配置选项 +^^^^^^^^^^^^^^^^^^^^^^^^^ +下列为在此次更新中废弃的重要配置选项。与以下配置有关或是依赖于下列配置的相关配置也已相应废弃。 + +- ``MBEDTLS_SSL_PROTO_SSL3``：原用于支持 SSL 3.0 +- ``MBEDTLS_SSL_PROTO_TLS1``：原用于支持 TLS 1.0 +- ``MBEDTLS_SSL_PROTO_TLS1_1``：原用于支持 TLS 1.1 +- ``MBEDTLS_SSL_PROTO_DTLS``：原用于支持 DTLS 1.1（当前版本仅支持 DTLS 1.2） +- ``MBEDTLS_DES_C``：原用于支持 3DES 密码套件 +- ``MBEDTLS_RC4_MODE``：原用于支持基于 RC4 的密码套件 + +.. note:: 上述仅列出了可通过 ``idf.py menuconfig`` 配置的主要选项。更多有关废弃选项的信息，请参考 `官方指南 `__。 + + +其他更新 +------------- + +禁用 Diffie-Hellman 密码交换模式 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +为避免 `安全风险 `__，当前版本已默认禁用 Diffie-Hellman 密码交换模式。以下为相应的禁用配置项： + +- ``MBEDTLS_DHM_C``：原用于支持 Diffie-Hellman-Merkle 模块 +- ``MBEDTLS_KEY_EXCHANGE_DHE_PSK``：原用于支持 Diffie-Hellman 预共享密钥 (PSK) TLS 认证模式 +- ``MBEDTLS_KEY_EXCHANGE_DHE_RSA``：原用于支持带有前缀的密码套件 ``TLS-DHE-RSA-WITH-`` + +.. note:: 在信号交换的初始步骤（即 ``client_hello``）中，服务器会在客户端提供的列表中选择一个密码。由于 DHE_PSK/DHE_RSA 密码已在本次更新中禁用，服务器将退回到一个替代密码。在极个别情况中，服务器不支持任何其他的代码，此时，初始步骤将失败。若要检索服务器所支持的密码列表，需要首先在客户端使用特定的密码连接服务器，可以使用 ``sslscan`` 等工具完成连接。 + +从 X509 库中移除 ``certs`` 模块 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- mbedtls 3.1 不再支持 ``mbedtls/certs.h`` 头文件。大多数应用程序支持从包含列表中安全删除该头文件。 + +对 ``esp_crt_bundle_set`` API 的重大更新 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 更新后，调用 :cpp:func:`esp_crt_bundle_set()` API 需要一个额外的参数 ``bundle_size``。该 API 的返回类型也从 ``void`` 变为了 :cpp:type:`esp_err_t`。 + +对 ``esp_ds_rsa_sign`` API 的重大更新 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 更新后，调用 :cpp:func:`esp_ds_rsa_sign()` API 无需再使用参数 ``mode``。 + +HTTPS 服务器 +------------ + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +更新 :cpp:type:`httpd_ssl_config_t` 结构体中持有不同证书的变量名。 + +.. list:: + * :cpp:member:`httpd_ssl_config::servercert`：原 ``cacert_pem`` + * :cpp:member:`httpd_ssl_config::servercert_len`：原 ``cacert_len`` + * :cpp:member:`httpd_ssl_config::cacert_pem`：原 ``client_verify_cert_pem`` + * :cpp:member:`httpd_ssl_config::cacert_len`：原 ``client_verify_cert_len`` + +:cpp:func:`httpd_ssl_stop` API 的返回类型从 ``void`` 变为了 :cpp:type:`esp_err_t`。 + +ESP HTTPS OTA +-------------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 函数 :cpp:func:`esp_https_ota` 现需以指向 :cpp:type:`esp_https_ota_config_t` 的指针作为参数，而非之前的指向 :cpp:type:`esp_http_client_config_t` 的指针。 + + +ESP-TLS +-------------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +私有化 ``esp_tls_t`` 结构体 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +更新后，:cpp:type:`esp_tls_t` 已完全私有化，用户无法直接访问其内部结构。之前需要通过 ESP-TLS 句柄获得的必要数据，现在可由对应的 getter/setter 函数获取。如需特定功能的 getter/setter 函数，请在 ESP-IDF 的 `Issue 板块 `__ 提出。 + + +下列为新增的 getter/setter 函数： + +.. list:: + * :cpp:func:`esp_tls_get_ssl_context`：从 ESP-TLS 句柄获取底层 ssl 栈的 ssl 上下文。 + +废弃函数及推荐的替代函数 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +下表总结了在 ESP-IDF v5.0 中废弃的函数以及相应的替代函数。 + +.. list-table:: + :widths: 50 50 + :header-rows: 1 + + * - 废弃函数 + - 替代函数 + * - ``esp_tls_conn_new()`` + - :cpp:func:`esp_tls_conn_new_sync` + * - ``esp_tls_conn_delete()`` + - :cpp:func:`esp_tls_conn_destroy` + +- 函数 :cpp:func:`esp_tls_conn_http_new` 现已废弃。请使用替代函数 :cpp:func:`esp_tls_conn_http_new_sync` （或其异步函数 :cpp:func:`esp_tls_conn_http_new_async` ）。请注意，使用替代函数时，需要额外的参数 :cpp:type:`esp_tls_t`，此参数必须首先通过 :cpp:func:`esp_tls_init` 函数进行初始化。 + +HTTP 服务器 +----------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``esp_http_server`` 现不再支持 ``http_server.h`` 头文件。请使用 ``esp_http_server.h``。 + +ESP HTTP 客户端 +--------------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 函数 :cpp:func:`esp_http_client_read` 和 :cpp:func:`esp_http_client_fetch_headers` 现在会返回额外的返回值 ``-ESP_ERR_HTTP_EAGAIN`` 用于处理超时错误，即数据准备好前就已调用超时的情况。 + + +TCP 传输 +------------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 更新后，出现连接超时的情况时，函数 :cpp:func:`esp_transport_read` 将返回 ``0``，对其他错误则返回 ``< 0``。请参考 :cpp:enum:`esp_tcp_transport_err_t`，查看所有可能的返回值。 + + +MQTT 客户端 +----------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- :cpp:type:`esp_mqtt_client_config_t` 的所有字段都分组存放在子结构体中。 + +以下为较为常用的配置选项： + +- 通过 :cpp:member:`esp_mqtt_client_config_t::broker::address::uri` 配置 MQTT Broker +- 通过 :cpp:member:`esp_mqtt_client_config_t::broker::verification` 配置 MQTT Broker 身份验证的相关安全问题 +- 通过 :cpp:member:`esp_mqtt_client_config_t::credentials::username` 配置客户端用户名 + + +ESP-Modbus +---------- + +重大更新（概述） +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +本次更新从 ESP-IDF 中移除了组件 ``freemodbus``，该组件已作为一个独立组件受到支持。可前往如下的独立仓库，查看更多有关 ``ESP-Modbus`` 的信息： + +* `GitHub 中的 ESP-Modbus 组件 `__ + +在新版应用程序中， ``main`` 组件文件夹应包括组件管理器清单文件 ``idf_component.yml``，如下所示： + +.. code-block:: text + + dependencies: + espressif/esp-modbus: + version: "^1.0" + +可以前往 `组件管理器注册表 `__ 找到 ``ESP-Modbus`` 组件。更多有关如何设置组件管理器的信息，请参考 `组件管理器文档 `__。 + +对于使用 ESP-IDF v4.x 及以后版本的应用程序，需要通过添加组件管理器清单文件 ``idf_component.yml`` 拉取新版 ``ESP-Modbus`` 组件。同时，在编译时，应去掉已过时的 ``freemodbus`` 组件。此项操作可通过项目 ``CMakeLists.txt`` 中的以下语句实现： + +.. code-block:: cmake + + set(EXCLUDE_COMPONENTS freemodbus)