From a6375c0db43ba99ced5db3d57c08f01a29f59028 Mon Sep 17 00:00:00 2001 From: Mahavir Jain Date: Sun, 21 Dec 2025 14:24:57 +0530 Subject: [PATCH] fix(mbedtls): misc updates post PSA crypto migration --- components/mbedtls/CMakeLists.txt | 48 +++++----- components/mbedtls/port/esp_timing.c | 94 ------------------- .../mbedtls/test_apps/main/test_psa_cmac.c | 7 -- .../mbedtls/test_apps/main/test_psa_gcm.c | 2 - .../release-6.x/6.0/provisioning.rst | 14 --- .../release-6.x/6.0/security.rst | 14 +++ .../release-6.x/6.0/security.rst | 88 ++++++++++++++++- 7 files changed, 119 insertions(+), 148 deletions(-) delete mode 100644 components/mbedtls/port/esp_timing.c diff --git a/components/mbedtls/CMakeLists.txt b/components/mbedtls/CMakeLists.txt index f11b9a7b4d..6468f5976c 100644 --- a/components/mbedtls/CMakeLists.txt +++ b/components/mbedtls/CMakeLists.txt @@ -215,29 +215,27 @@ list(APPEND mbedtls_targets everest p256m) set(mbedtls_target_sources "${COMPONENT_DIR}/port/mbedtls_debug.c" "${COMPONENT_DIR}/port/esp_platform_time.c") -if(CONFIG_MBEDTLS_VER_4_X_SUPPORT) - list(APPEND mbedtls_target_sources "${COMPONENT_DIR}/port/esp_psa_crypto_init.c") - # Add ESP-IDF NVS-based PSA ITS implementation - # Only compile esp_psa_its.c if nvs_flash component is available - if(NOT ${IDF_TARGET} STREQUAL "linux") - if(IDF_BUILD_V2) - # For v2: conditionally compile source and link only if nvs_flash target exists - target_sources( - tfpsacrypto PRIVATE - "$<$:${COMPONENT_DIR}/port/psa_crypto_storage/esp_psa_its.c>" - ) - target_link_libraries(tfpsacrypto PRIVATE "$<$:idf::nvs_flash>") - # Define compile definition to indicate ESP-IDF PSA ITS implementation is available - target_compile_definitions(tfpsacrypto PRIVATE "$<$:ESP_PSA_ITS_AVAILABLE>") - else() - # For v1: check if component is in build before adding source and linking - idf_build_get_property(build_components BUILD_COMPONENTS) - if(nvs_flash IN_LIST build_components) - target_sources(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/psa_crypto_storage/esp_psa_its.c") - idf_component_get_property(nvs_flash_lib nvs_flash COMPONENT_LIB) - target_link_libraries(tfpsacrypto PRIVATE ${nvs_flash_lib}) - target_compile_definitions(tfpsacrypto PRIVATE ESP_PSA_ITS_AVAILABLE) - endif() +list(APPEND mbedtls_target_sources "${COMPONENT_DIR}/port/esp_psa_crypto_init.c") +# Add ESP-IDF NVS-based PSA ITS implementation +# Only compile esp_psa_its.c if nvs_flash component is available +if(NOT ${IDF_TARGET} STREQUAL "linux") + if(IDF_BUILD_V2) + # For v2: conditionally compile source and link only if nvs_flash target exists + target_sources( + tfpsacrypto PRIVATE + "$<$:${COMPONENT_DIR}/port/psa_crypto_storage/esp_psa_its.c>" + ) + target_link_libraries(tfpsacrypto PRIVATE "$<$:idf::nvs_flash>") + # Define compile definition to indicate ESP-IDF PSA ITS implementation is available + target_compile_definitions(tfpsacrypto PRIVATE "$<$:ESP_PSA_ITS_AVAILABLE>") + else() + # For v1: check if component is in build before adding source and linking + idf_build_get_property(build_components BUILD_COMPONENTS) + if(nvs_flash IN_LIST build_components) + target_sources(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/psa_crypto_storage/esp_psa_its.c") + idf_component_get_property(nvs_flash_lib nvs_flash COMPONENT_LIB) + target_link_libraries(tfpsacrypto PRIVATE ${nvs_flash_lib}) + target_compile_definitions(tfpsacrypto PRIVATE ESP_PSA_ITS_AVAILABLE) endif() endif() endif() @@ -337,9 +335,7 @@ endif() if(NOT ${IDF_TARGET} STREQUAL "linux") target_sources(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/esp_hardware.c") endif() -target_sources(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/esp_mem.c" - # "${COMPONENT_DIR}/port/esp_timing.c" -) +target_sources(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/esp_mem.c") if(CONFIG_SOC_AES_SUPPORTED) target_include_directories(tfpsacrypto PRIVATE "${COMPONENT_DIR}/port/aes/include") diff --git a/components/mbedtls/port/esp_timing.c b/components/mbedtls/port/esp_timing.c deleted file mode 100644 index 96858f765a..0000000000 --- a/components/mbedtls/port/esp_timing.c +++ /dev/null @@ -1,94 +0,0 @@ -/* - * Portable interface to the CPU cycle counter - * - * SPDX-FileCopyrightText: The Mbed TLS Contributors - * - * SPDX-License-Identifier: Apache-2.0 - * - * SPDX-FileContributor: 2016-2022 Espressif Systems (Shanghai) CO LTD - */ -/* - * mbedtls_timing_get_timer()m mbedtls_timing_set_delay() and - * mbedtls_timing_set_delay only abstracted from mbedtls/library/timing.c - * as that does not build on ESP-IDF but these 2 functions are needed for - * DTLS (in particular mbedtls_ssl_set_timer_cb() must be called for DTLS - * which requires these 2 delay functions). - */ - -#include - -#if !defined(MBEDTLS_ESP_TIMING_C) - -#include -#include "mbedtls/timing.h" - -struct _hr_time -{ - struct timeval start; -}; - -unsigned long mbedtls_timing_get_timer( struct mbedtls_timing_hr_time *val, int reset ) -{ - struct _hr_time *t = (struct _hr_time *) val; - - if( reset ) - { - gettimeofday( &t->start, NULL ); - return( 0 ); - } - else - { - unsigned long delta; - struct timeval now; - gettimeofday( &now, NULL ); - delta = ( now.tv_sec - t->start.tv_sec ) * 1000ul - + ( now.tv_usec - t->start.tv_usec ) / 1000; - return( delta ); - } -} - -/* - * Set delays to watch - */ -void mbedtls_timing_set_delay( void *data, uint32_t int_ms, uint32_t fin_ms ) -{ - mbedtls_timing_delay_context *ctx = (mbedtls_timing_delay_context *) data; - - ctx->MBEDTLS_PRIVATE(int_ms) = int_ms; - ctx->MBEDTLS_PRIVATE(fin_ms) = fin_ms; - - if( fin_ms != 0 ) - (void) mbedtls_timing_get_timer( &ctx->MBEDTLS_PRIVATE(timer), 1 ); -} - -/* - * Get number of delays expired - */ -int mbedtls_timing_get_delay( void *data ) -{ - mbedtls_timing_delay_context *ctx = (mbedtls_timing_delay_context *) data; - unsigned long elapsed_ms; - - if( ctx->MBEDTLS_PRIVATE(fin_ms) == 0 ) - return( -1 ); - - elapsed_ms = mbedtls_timing_get_timer( &ctx->MBEDTLS_PRIVATE(timer), 0 ); - - if( elapsed_ms >= ctx->MBEDTLS_PRIVATE(fin_ms) ) - return( 2 ); - - if( elapsed_ms >= ctx->MBEDTLS_PRIVATE(int_ms) ) - return( 1 ); - - return( 0 ); -} - -/* - * Get the final delay. - */ -uint32_t mbedtls_timing_get_final_delay( const mbedtls_timing_delay_context *data ) -{ - return( data->MBEDTLS_PRIVATE(fin_ms) ); -} - -#endif /* MBEDTLS_ESP_TIMING_C */ diff --git a/components/mbedtls/test_apps/main/test_psa_cmac.c b/components/mbedtls/test_apps/main/test_psa_cmac.c index a22878f263..3d464f1210 100644 --- a/components/mbedtls/test_apps/main/test_psa_cmac.c +++ b/components/mbedtls/test_apps/main/test_psa_cmac.c @@ -100,7 +100,6 @@ TEST_CASE("PSA CMAC AES-128 test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); free(cmac); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC AES-256 test", "[psa_cmac]") @@ -144,7 +143,6 @@ TEST_CASE("PSA CMAC AES-256 test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); free(cmac); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC AES-128 multipart test", "[psa_cmac]") @@ -197,7 +195,6 @@ TEST_CASE("PSA CMAC AES-128 multipart test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); free(cmac); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC AES-128 multipart verify test", "[psa_cmac]") @@ -257,7 +254,6 @@ TEST_CASE("PSA CMAC AES-128 multipart verify test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); free(cmac); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC zero-length test", "[psa_cmac]") @@ -301,7 +297,6 @@ TEST_CASE("PSA CMAC zero-length test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); free(cmac); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC memory alignment test", "[psa_cmac]") @@ -355,7 +350,6 @@ TEST_CASE("PSA CMAC memory alignment test", "[psa_cmac]") psa_destroy_key(key_id); free(cmac_internal); free(cmac_dma); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA CMAC verify failure test", "[psa_cmac]") @@ -393,6 +387,5 @@ TEST_CASE("PSA CMAC verify failure test", "[psa_cmac]") // Cleanup psa_destroy_key(key_id); - // mbedtls_psa_crypto_free(); } #endif /* CONFIG_MBEDTLS_CMAC_C */ diff --git a/components/mbedtls/test_apps/main/test_psa_gcm.c b/components/mbedtls/test_apps/main/test_psa_gcm.c index 45e3493a41..d66c611cea 100644 --- a/components/mbedtls/test_apps/main/test_psa_gcm.c +++ b/components/mbedtls/test_apps/main/test_psa_gcm.c @@ -129,7 +129,6 @@ TEST_CASE("PSA ARIA-GCM multipart", "[psa-gcm]") /* Destroy the key */ psa_destroy_key(key_id); - // mbedtls_psa_crypto_free(); } TEST_CASE("PSA ARIA-GCM one-shot", "[psa-gcm]") @@ -206,5 +205,4 @@ TEST_CASE("PSA ARIA-GCM one-shot", "[psa-gcm]") /* Destroy the key */ psa_destroy_key(key_id); - // mbedtls_psa_crypto_free(); } diff --git a/docs/en/migration-guides/release-6.x/6.0/provisioning.rst b/docs/en/migration-guides/release-6.x/6.0/provisioning.rst index 16fe793985..24f327c400 100644 --- a/docs/en/migration-guides/release-6.x/6.0/provisioning.rst +++ b/docs/en/migration-guides/release-6.x/6.0/provisioning.rst @@ -35,20 +35,6 @@ The API names have been updated after migrating to the new component. Most chang "wifi_prov_mgr_reset_sm_state_on_failure", "network_prov_mgr_reset_wifi_sm_state_on_failure" "wifi_prov_mgr_reset_sm_state_for_reprovision", "network_prov_mgr_reset_wifi_sm_state_for_reprovision" -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). - - **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. - - **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. - Configuration Changes --------------------- diff --git a/docs/en/migration-guides/release-6.x/6.0/security.rst b/docs/en/migration-guides/release-6.x/6.0/security.rst index 2b07af1a9b..5c2b48cce9 100644 --- a/docs/en/migration-guides/release-6.x/6.0/security.rst +++ b/docs/en/migration-guides/release-6.x/6.0/security.rst @@ -86,6 +86,20 @@ The following deprecated functions have been removed: Note that the new AES functions return error codes for better error handling, unlike the old void functions. +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). + + **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. + + **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. + Bootloader Support ------------------ diff --git 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 index 8dc3b8da99..cc818d0201 100644 --- 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 @@ -1,5 +1,5 @@ 安全性 -======= +====== :link_to_translation:`en:[English]` @@ -12,7 +12,71 @@ Mbed TLS SHA 模块头文件 ``sha/sha_dma.h`` 和 ``sha/sha_block.h`` 也已废弃并被移除，请改为包含 ``sha/sha_core.h``。 -**已移除的废弃 API** +PSA Crypto 迁移 +~~~~~~~~~~~~~~~ + +在 ESP-IDF v6.0 中，多个 ESP-IDF 组件已从使用传统 Mbed TLS 加密 API（例如 ``mbedtls_sha*_*()``、``mbedtls_md*_*()`` 等）迁移到使用 `PSA Crypto API `__。 + +此迁移使 ESP-IDF 与 Mbed TLS v4.x 保持一致，其中 PSA Crypto 是主要的加密接口，并支持在可用时通过 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 内部/私有声明的应用程序。 + +- **重大变更**: 在 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 占用，具体取决于启用的功能。以下是参考数据： + + .. 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 迁移指南 ` +- :idf_file:`TF-PSA-Crypto 1.0 迁移指南 ` +- :idf_file:`TF-PSA-Crypto PSA 过渡说明 ` + +上游 Mbed TLS PSA 说明 +^^^^^^^^^^^^^^^^^^^^^^ + +一些以前应用程序可能访问过的数据结构和内部实现，在使用基于 PSA 的 Mbed TLS 版本时不再可用。如果你的应用程序依赖于直接访问 Mbed TLS 内部状态（例如作为结构体字段的熵/DRBG 上下文），请迁移到受支持的公共 API。 + +ESP-IDF 上的 PSA 持久存储 (ITS) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ESP-IDF 提供了由 NVS 支持的 PSA 内部可信存储 (ITS) 实现，因此可以在没有文件系统的情况下使用 PSA 持久存储。如果你的应用程序使用 PSA 持久密钥/存储，请确保 NVS 在首次使用前可用并已初始化。 + +已移除的废弃 API（Mbed TLS / 加密） +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 以下废弃函数已被移除： @@ -22,8 +86,22 @@ Mbed TLS 注意，新的 AES 函数返回错误代码以提供更好的错误处理，与返回 void 的旧函数不同。 +BluFi +----- + +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 加密/协议实现构建的现有 BluFi 客户端应用程序（例如手机应用）可能无法再与使用 ESP-IDF v6.0 构建的设备互操作。这通常表现为尝试配网时 BluFi 协商/连接失败。 + + **需要采取的措施**: 请同时更新两端： + + - 将设备固件更新到 ESP-IDF v6.0。 + - 将 BluFi 客户端应用程序更新到与 ESP-IDF v6.0 使用的更新后 BluFi 协议/安全协商兼容的版本。 + 引导加载程序支持 ------------------- +---------------- **已移除的废弃 API** @@ -34,6 +112,6 @@ Mbed TLS .. only:: SOC_HMAC_SUPPORTED NVS 安全方案 - ---------------- + ------------ - - 当 SoC 具备 HMAC 外设并启用了 flash 加密时，如果同时还启用了 NVS 加密，则默认会选择基于 HMAC 的 NVS 加密方案，而不是基于 flash 加密的方案。如果你的应用程序之前基于 flash 加密，则需要通过 ``menuconfig`` 或项目的 ``sdkconfig`` 文件，手动将 NVS 加密方案从 HMAC 配置为 flash 加密（即设置 ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y``）。 + - 当 SoC 具备 HMAC 外设并启用了 flash 加密时，如果同时还启用了 NVS 加密，则默认会选择基于 HMAC 的 NVS 加密方案，而不是基于 flash 加密的方案。如果你的应用程序之前使用基于 flash 加密的方案，则需要通过 ``menuconfig`` 或项目的 ``sdkconfig`` 文件，手动将 NVS 加密方案从 HMAC 配置为 flash 加密（即设置 ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y``）。