Merge branch 'docs/sync_trans_for_psa_migration' into 'master'

docs: Sync translation update for PSA migration See merge request espressif/esp-idf!44910
2026-01-19 17:55:43 +00:00 · 2026-01-13 14:12:43 +08:00
parent 111ac6257f a68b0c60d5
commit f58b82b928
3 changed files with 86 additions and 82 deletions
--- a/docs/en/migration-guides/release-6.x/6.0/security.rst
+++ b/docs/en/migration-guides/release-6.x/6.0/security.rst
@@ -20,7 +20,7 @@ In ESP-IDF v6.0, multiple ESP-IDF components have been migrated from using legac
 This migration aligns ESP-IDF with Mbed TLS v4.x, where PSA Crypto is the primary cryptography interface, and it enables the use of ESP-IDF hardware acceleration through PSA drivers where available.

 Mbed TLS v4.0 migration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^

 ESP-IDF v6.0 updates to Mbed TLS v4.0, where **PSA Crypto is the primary cryptography interface** (TF-PSA-Crypto provides cryptography; Mbed TLS focuses on TLS and X.509). This can impact applications directly using Mbed TLS cryptography primitives, TLS configuration, or Mbed TLS internal/private declarations.

@@ -30,33 +30,35 @@ ESP-IDF v6.0 updates to Mbed TLS v4.0, where **PSA Crypto is the primary cryptog
 - **Breaking change**: APIs that previously required an application-provided RNG callback (``f_rng``, ``p_rng``) have changed in Mbed TLS v4.0 to use the PSA RNG instead. Update application code to the new prototypes (for example X.509 write APIs, SSL cookie setup, and SSL ticket setup).
 - **Breaking change**: TLS 1.2 / DTLS 1.2 interoperability may be affected because Mbed TLS v4.0 removes support for key exchanges based on finite-field DHE and RSA key exchange without forward secrecy (and static ECDH). If a peer requires removed suites, TLS connections may fail; update server/client cipher suite configuration accordingly.
 - **Breaking change**: certificates/peers using elliptic curves of less than 250 bits (for example secp192r1/secp224r1) are no longer supported in certificates and in TLS.
- **Note**: avoid relying on Mbed TLS private declarations (for example headers under ``mbedtls/private/`` or declarations enabled via ``MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`` / ``MBEDTLS_ALLOW_PRIVATE_ACCESS``). Such private interfaces may change without notice.
- **Note**: the PSA Crypto migration (TF-PSA-Crypto) can increase flash footprint, depending on the features enabled. As reference points:
+- **Note**:

-  .. list-table::
-     :header-rows: 1
-     :widths: 30 15 15 15 10
+  - void relying on Mbed TLS private declarations (for example headers under ``mbedtls/private/`` or declarations enabled via ``MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`` / ``MBEDTLS_ALLOW_PRIVATE_ACCESS``). Such private interfaces may change without notice.
+  - The PSA Crypto migration (TF-PSA-Crypto) can increase flash footprint, depending on the features enabled. As reference points:

-     * - Example
-       - non PSA build (bytes)
-       - PSA migration (bytes)
-       - Diff (bytes)
-       - Diff (%)
-     * - :example:`protocols/esp_http_client`
-       - 609041
-       - 646293
-       - 37252
-       - 5.76
-     * - :example:`protocols/https_server`
-       - 871021
-       - 898717
-       - 27696
-       - 3.08
-     * - :example:`protocols/http_server/simple`
-       - 785825
-       - 826909
-       - 41084
-       - 4.97
+    .. list-table::
+       :header-rows: 1
+       :widths: 30 15 15 15 10
+
+       * - Example
+         - non PSA build (bytes)
+         - PSA migration (bytes)
+         - Diff (bytes)
+         - Diff (%)
+       * - :example:`protocols/esp_http_client`
+         - 609041
+         - 646293
+         - 37252
+         - 5.76
+       * - :example:`protocols/https_server`
+         - 871021
+         - 898717
+         - 27696
+         - 3.08
+       * - :example:`protocols/http_server/simple`
+         - 785825
+         - 826909
+         - 41084
+         - 4.97

 References
 ^^^^^^^^^^
@@ -91,14 +93,14 @@ BluFi

 BluFi (Wi-Fi provisioning over BLE) is affected by the Mbed TLS v4.x / PSA Crypto migration in ESP-IDF v6.0.

- **Breaking change**: The BluFi protocol version has been updated (``BTC_BluFi_SUB_VER`` bumped from ``0x03`` to ``0x04``). The BluFi security negotiation implementation used by ESP-IDF has also been updated to use PSA Crypto (see the updated ``examples/bluetooth/blufi`` example).
+- **Breaking change**: The BluFi protocol version has been updated (``BTC_BluFi_SUB_VER`` bumped from ``0x03`` to ``0x04``). The BluFi security negotiation implementation in ESP-IDF has been migrated to use PSA Crypto (see the updated ``examples/bluetooth/blufi`` example).

-  **Impact**: Existing BluFi client applications (for example, mobile apps) built against the older BluFi crypto/protocol implementation may no longer interoperate with devices built with ESP-IDF v6.0. This typically shows up as BluFi negotiation/connection failures when attempting to provision.
+- **Impact**: Existing BluFi client applications (for example, mobile apps) built against the previous BluFi crypto/protocol implementation may no longer interoperate with devices built with ESP-IDF v6.0. This typically shows up as BluFi negotiation or connection failures during provisioning.

-  **Required action**: Update both sides together:
+- **Required action**: Update both sides together:

  - Update the device firmware to ESP-IDF v6.0.
-  - Update the BluFi client application to a version compatible with the updated BluFi protocol/security negotiation used by ESP-IDF v6.0.
+  - Update the BluFi client application to a version compatible with the updated BluFi protocol and security negotiation used by ESP-IDF v6.0.

 Bootloader Support
 ------------------
--- a/docs/zh_CN/migration-guides/release-6.x/6.0/provisioning.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.0/provisioning.rst
@@ -6,7 +6,7 @@
 重大变更
 --------

-本次更新从 ESP-IDF 中移除了组件 ``wifi_provisioning``，更名为 ``network_provisioning`` 并作为一个独立组件受到支持。该组件增加了对Thread 配网的支持。可在乐鑫组件注册表中，查看更多有关 ``network_provisioning`` 的信息：
+本次更新从 ESP-IDF 中移除了组件 ``wifi_provisioning``，更名为 ``network_provisioning`` 并作为一个独立组件受到支持。该组件增加了对 Thread 配网的支持。可在乐鑫组件注册表中，查看更多有关 ``network_provisioning`` 的信息：

 * `network_provisioning 组件 <https://components.espressif.com/component/espressif/network_provisioning>`__

--- a/docs/zh_CN/migration-guides/release-6.x/6.0/security.rst
+++ b/docs/zh_CN/migration-guides/release-6.x/6.0/security.rst
@@ -13,70 +13,72 @@ Mbed TLS
    SHA 模块头文件 ``sha/sha_dma.h`` 和 ``sha/sha_block.h`` 也已废弃并被移除，请改为包含 ``sha/sha_core.h``。

 PSA Crypto 迁移
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~

-在 ESP-IDF v6.0 中，多个 ESP-IDF 组件已从使用传统 Mbed TLS 加密 API（例如 ``mbedtls_sha*_*()``、``mbedtls_md*_*()`` 等）迁移到使用 `PSA Crypto API <https://arm-software.github.io/psa-api/>`__。
+在 ESP-IDF v6.0 中，多个 ESP-IDF 组件已完成从传统 Mbed TLS 加密 API（例如 ``mbedtls_sha*_*()``、``mbedtls_md*_*()`` 等）向 `PSA Crypto API <https://arm-software.github.io/psa-api/>`__ 的迁移。

-此迁移使 ESP-IDF 与 Mbed TLS v4.x 保持一致，其中 PSA Crypto 是主要的加密接口，并支持在可用时通过 PSA 驱动使用 ESP-IDF 硬件加速。
+此次迁移使 ESP-IDF 与将 PSA Crypto 作为主要加密接口的 Mbed TLS v4.x 保持同步，并能够在支持时通过 PSA 驱动程序启用 ESP-IDF 硬件加速功能。

 Mbed TLS v4.0 迁移
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^

-ESP-IDF v6.0 更新到 Mbed TLS v4.0，其中 **PSA Crypto 是主要的加密接口** （TF-PSA-Crypto 提供加密功能；Mbed TLS 专注于 TLS 和 X.509）。这可能会影响直接使用 Mbed TLS 加密原语、TLS 配置或 Mbed TLS 内部/私有声明的应用程序。
+ESP-IDF v6.0 已升级至 Mbed TLS v4.0，**PSA Crypto 成为主要加密接口** （TF-PSA-Crypto 提供加密功能，Mbed TLS 侧重于 TLS 和 X.509）。此变更可能直接影响使用 Mbed TLS 加密原语、TLS 配置或 Mbed TLS 内部/私有声明的应用程序。

- **重大变更**: 在 Mbed TLS v4.0 中，**大多数传统加密 API 已被移除**，PSA Crypto 是主要接口。如果你的应用程序直接使用传统 ``mbedtls_*`` 加密原语，你可能需要迁移到 PSA Crypto API。
- **重大变更**: 在任何加密操作之前，包括间接操作（如解析密钥/证书或启动 TLS 握手），都必须调用 ``psa_crypto_init()``。ESP-IDF 会在正常启动期间初始化 PSA；但是，在正常启动序列之前运行的代码必须显式调用 ``psa_crypto_init()``。
- **新增 API**: 新增了 ``esp_ecdsa_free_pk_context(mbedtls_pk_context *key_ctx)`` （位于 ``ecdsa/ecdsa_alt.h``）。如果你的应用程序使用 ``esp_ecdsa_set_pk_context()`` 用硬件支持的 ECDSA 密钥初始化 PK 上下文，请使用 ``esp_ecdsa_free_pk_context()`` 释放它。在基于 PSA 的 Mbed TLS v4.x 中，``mbedtls_pk_free()`` 不会释放在这种情况下手动创建的密钥对结构。
- **重大变更**: 以前需要应用程序提供 RNG 回调（``f_rng``、``p_rng``）的 API 在 Mbed TLS v4.0 中已更改为使用 PSA RNG。请将应用程序代码更新为新的函数原型（例如 X.509 写入 API、SSL cookie 设置和 SSL ticket 设置）。
- **重大变更**: TLS 1.2 / DTLS 1.2 的互操作性可能会受到影响，因为 Mbed TLS v4.0 移除了对基于有限域 DHE 和不具有前向保密性的 RSA 密钥交换（以及静态 ECDH）的支持。如果对等方需要已移除的套件，TLS 连接可能会失败；请相应更新服务器/客户端的密码套件配置。
- **重大变更**: 使用少于 250 位椭圆曲线（例如 secp192r1/secp224r1）的证书/对等方在证书和 TLS 中不再受支持。
- **注意**: 避免依赖 Mbed TLS 私有声明（例如 ``mbedtls/private/`` 下的头文件或通过 ``MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`` / ``MBEDTLS_ALLOW_PRIVATE_ACCESS`` 启用的声明）。这些私有接口可能会在没有通知的情况下更改。
- **注意**: PSA Crypto 迁移（TF-PSA-Crypto）可能会增加 flash 占用，具体取决于启用的功能。以下是参考数据：
+- **重大变更**：在 Mbed TLS v4.0 中，**大多数传统加密 API 已被移除**，PSA Crypto 成为主要接口。如果应用直接使用传统的 ``mbedtls_*`` 加密原语，则无法直接兼容，需迁移到 PSA Crypto API。
+- **重大变更**：在执行任何加密操作之前（包括解析密钥/证书或启动 TLS 握手等操作），必须调用 ``psa_crypto_init()``。ESP-IDF 在常规启动过程中会初始化 PSA，因此大多数应用保持兼容；但对于早于常规启动流程运行的代码，需显式调用 ``psa_crypto_init()``。
+- **新增 API**：新增 ``esp_ecdsa_free_pk_context(mbedtls_pk_context *key_ctx)``，参见 ``ecdsa/ecdsa_alt.h``。如果应用使用 ``esp_ecdsa_set_pk_context()`` 初始化包含硬件 ECDSA 密钥的 PK 上下文，应使用 ``esp_ecdsa_free_pk_context()`` 进行释放。在基于 PSA 的 Mbed TLS v4.x 中，``mbedtls_pk_free()`` 无法释放此种情况下手动创建的密钥对结构。
+- **重大变更**：原需应用提供 RNG 回调（``f_rng``、``p_rng``）的 API，在 Mbed TLS v4.0 中已改为使用 PSA RNG。使用旧函数原型的代码将无法直接兼容，需要更新为新的 API 定义（例如 X.509 写入 API、SSL cookie 设置以及 SSL ticket 设置）。
+- **重大变更**：TLS 1.2 / DTLS 1.2 的互操作性可能受到影响，因为 Mbed TLS v4.0 移除了对基于有限域 DHE、无前向保密的 RSA 密钥交换（以及静态 ECDH）的支持。如果对等端需要使用已移除的密码套件，TLS 连接将不兼容并可能失败；需相应更新服务器或客户端的密码套件配置。
+- **重大变更**：证书或对等端中使用的椭圆曲线位数小于 250 位（例如 secp192r1/secp224r1）已不再受支持。
+- **注意**：

-  .. list-table::
-     :header-rows: 1
-     :widths: 30 15 15 15 10
+  - 避免依赖 Mbed TLS 的私有声明（例如 ``mbedtls/private/`` 目录下的头文件，或通过 ``MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`` / ``MBEDTLS_ALLOW_PRIVATE_ACCESS`` 启用的声明）。这些私有接口可能未经通知即发生变更。
+  - PSA Crypto 迁移 (TF-PSA-Crypto) 可能会增加 flash 占用，具体取决于启用的功能。以下示例可作为参考：

-     * - 示例
-       - 非 PSA 构建 (字节)
-       - PSA 迁移后 (字节)
-       - 差异 (字节)
-       - 差异 (%)
-     * - :example:`protocols/esp_http_client`
-       - 609041
-       - 646293
-       - 37252
-       - 5.76
-     * - :example:`protocols/https_server`
-       - 871021
-       - 898717
-       - 27696
-       - 3.08
-     * - :example:`protocols/http_server/simple`
-       - 785825
-       - 826909
-       - 41084
-       - 4.97
+    .. list-table::
+       :header-rows: 1
+       :widths: 30 15 15 15 10

-参考资料
-^^^^^^^^
+       * - 示例
+         - 非 PSA 构建（字节）
+         - PSA 迁移（字节）
+         - 差值（字节）
+         - 差值（%）
+       * - :example:`protocols/esp_http_client`
+         - 609041
+         - 646293
+         - 37252
+         - 5.76
+       * - :example:`protocols/https_server`
+         - 871021
+         - 898717
+         - 27696
+         - 3.08
+       * - :example:`protocols/http_server/simple`
+         - 785825
+         - 826909
+         - 41084
+         - 4.97
+
+参考文档
+^^^^^^^^^^

 - :idf_file:`Mbed TLS 4.0 迁移指南 <components/mbedtls/mbedtls/docs/4.0-migration-guide.md>`
 - :idf_file:`TF-PSA-Crypto 1.0 迁移指南 <components/mbedtls/mbedtls/tf-psa-crypto/docs/1.0-migration-guide.md>`
 - :idf_file:`TF-PSA-Crypto PSA 过渡说明 <components/mbedtls/mbedtls/tf-psa-crypto/docs/psa-transition.md>`

 上游 Mbed TLS PSA 说明
-^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^

-一些以前应用程序可能访问过的数据结构和内部实现，在使用基于 PSA 的 Mbed TLS 版本时不再可用。如果你的应用程序依赖于直接访问 Mbed TLS 内部状态（例如作为结构体字段的熵/DRBG 上下文），请迁移到受支持的公共 API。
+部分应用程序此前可能访问的数据结构和内部状态，在使用基于 PSA 的 Mbed TLS 版本时已不可用。如果应用依赖直接访问 Mbed TLS 的内部状态（例如以结构体字段形式访问熵/DRBG 上下文），请迁移到受支持的公共 API。

-ESP-IDF 上的 PSA 持久存储 (ITS)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ESP-IDF 中的 PSA 持久化存储 (ITS)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-ESP-IDF 提供了由 NVS 支持的 PSA 内部可信存储 (ITS) 实现，因此可以在没有文件系统的情况下使用 PSA 持久存储。如果你的应用程序使用 PSA 持久密钥/存储，请确保 NVS 在首次使用前可用并已初始化。
+ESP-IDF 提供了基于 NVS 的 PSA 内部可信存储 (ITS) 实现，因此无需文件系统即可使用 PSA 持久化存储。如果应用使用 PSA 持久化密钥/存储，请确保在首次使用前 NVS 已就绪并初始化完毕。

-已移除的废弃 API（Mbed TLS / 加密）
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+已移除的弃用 API (Mbed TLS / crypto)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 以下废弃函数已被移除：

@@ -89,16 +91,16 @@ ESP-IDF 提供了由 NVS 支持的 PSA 内部可信存储 (ITS) 实现，因此
 BluFi
 -----

-BluFi（通过 BLE 进行 Wi-Fi 配网）受 ESP-IDF v6.0 中 Mbed TLS v4.x / PSA Crypto 迁移的影响。
+BluFi（基于 BLE 的 Wi-Fi 配网）功能受到 ESP-IDF v6.0 中 Mbed TLS v4.x / PSA Crypto 迁移的影响。

- **重大变更**: BluFi 协议版本已更新（``BTC_BluFi_SUB_VER`` 从 ``0x03`` 升级到 ``0x04``）。ESP-IDF 使用的 BluFi 安全协商实现也已更新为使用 PSA Crypto（请参阅更新后的 ``examples/bluetooth/blufi`` 示例）。
+- **重大变更**：BluFi 协议版本已更新（``BTC_BluFi_SUB_VER`` 从 ``0x03`` 升级至 ``0x04``）。ESP-IDF 使用的 BluFi 安全协商实现也同步更新为基于 PSA Crypto 的方案（参考更新后的 ``examples/bluetooth/BluFi`` 示例）。

-  **影响**: 基于旧版 BluFi 加密/协议实现构建的现有 BluFi 客户端应用程序（例如手机应用）可能无法再与使用 ESP-IDF v6.0 构建的设备互操作。这通常表现为尝试配网时 BluFi 协商/连接失败。
+- **影响**：基于旧版 BluFi 加密/协议实现构建的现有 BluFi 客户端应用（例如手机 App），可能无法再与使用 ESP-IDF v6.0 构建的设备互通。通常表现为在配网时出现 BluFi 协商或连接失败。

-  **需要采取的措施**: 请同时更新两端：
+- **必要操作**：请同步更新两端应用：

-  - 将设备固件更新到 ESP-IDF v6.0。
-  - 将 BluFi 客户端应用程序更新到与 ESP-IDF v6.0 使用的更新后 BluFi 协议/安全协商兼容的版本。
+  - 将设备固件升级至 ESP-IDF v6.0。
+  - 将 BluFi 客户端应用更新至兼容 ESP-IDF v6.0 新版 BluFi 协议和安全协商的版本。

 引导加载程序支持
 ----------------