Merge branch 'feat/nvs_flash_deregister_sec_scheme' into 'master'

feat(nvs_flash): Added an API to deregister the NVS security scheme context Closes IDF-12456 and IDFGH-16210 See merge request espressif/esp-idf!41073
2025-10-02 10:00:57 +02:00 · 2025-09-22 11:11:34 +05:30
parent 33f92c8fc8 536ec82dd3
commit 649741fa9d
25 changed files with 73 additions and 13 deletions
--- a/components/esp_tee/test_apps/tee_cli_app/sdkconfig.ci.sb_fe
+++ b/components/esp_tee/test_apps/tee_cli_app/sdkconfig.ci.sb_fe
@@ -9,6 +9,8 @@ CONFIG_SECURE_BOOT_SIGNING_KEY="test_keys/secure_boot_signing_key.pem"
 # Flash Encryption
 CONFIG_SECURE_FLASH_ENC_ENABLED=y
 CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y
+# NVS Encryption
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 # TEE Secure Storage: Release mode
 CONFIG_SECURE_TEE_SEC_STG_MODE_RELEASE=y
--- a/components/nvs_flash/CMakeLists.txt
+++ b/components/nvs_flash/CMakeLists.txt
@@ -7,10 +7,11 @@ if(BOOTLOADER_BUILD)
             "src/nvs_bootloader_xts_aes.c")

    set(requires "esp_partition")
+    set(priv_requires "mbedtls" "nvs_sec_provider")

    idf_component_register(SRCS "${srcs}"
                        REQUIRES "${requires}"
-                        PRIV_REQUIRES "mbedtls"
+                        PRIV_REQUIRES "${priv_requires}"
                        INCLUDE_DIRS "include"
                        PRIV_INCLUDE_DIRS "private_include"
    )
@@ -60,10 +61,9 @@ else()
            "src/nvs_bootloader.c")

    set(requires esp_partition)
-    if(${target} STREQUAL "linux")
    set(priv_requires spi_flash)
-    else()
-        set(priv_requires spi_flash esp_libc esptool_py)
+    if(NOT ${target} STREQUAL "linux")
+        list(APPEND priv_requires esp_libc esptool_py nvs_sec_provider)
    endif()

    idf_component_register(SRCS "${srcs}"
--- a/components/nvs_flash/include/nvs_flash.h
+++ b/components/nvs_flash/include/nvs_flash.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -278,6 +278,13 @@ esp_err_t nvs_flash_read_security_cfg(const esp_partition_t* partition, nvs_sec_
 */
 esp_err_t nvs_flash_register_security_scheme(nvs_sec_scheme_t *scheme_cfg);

+/**
+ * @brief Deregister the security scheme previously registered using
+ *        nvs_flash_register_security_scheme
+ *
+ */
+void nvs_flash_deregister_security_scheme(void);
+
 /**
 * @brief   Fetch the configuration structure for the default active
 *          security scheme for NVS encryption
--- a/components/nvs_flash/src/nvs_api.cpp
+++ b/components/nvs_flash/src/nvs_api.cpp
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */
@@ -736,6 +736,11 @@ extern "C" esp_err_t nvs_flash_register_security_scheme(nvs_sec_scheme_t *scheme
    return ESP_OK;
 }

+extern "C" void nvs_flash_deregister_security_scheme(void)
+{
+    memset(&nvs_sec_default_scheme_cfg, 0x00, sizeof(nvs_sec_scheme_t));
+}
+
 extern "C" nvs_sec_scheme_t *nvs_flash_get_default_security_scheme(void)
 {
    return &nvs_sec_default_scheme_cfg;
--- a/components/nvs_sec_provider/CMakeLists.txt
+++ b/components/nvs_sec_provider/CMakeLists.txt
@@ -4,10 +4,12 @@ if(${target} STREQUAL "linux")
    return() # This component is not supported by the POSIX/Linux simulator
 endif()

-if(BOOTLOADER_BUILD)
+if(NOT CONFIG_NVS_SEC_KEY_PROTECT_NONE)
+    if(BOOTLOADER_BUILD)
        set(srcs "nvs_bootloader_sec_provider.c")
-else()
+    else()
        set(srcs "nvs_sec_provider.c")
+    endif()
 endif()

 idf_component_register(SRCS ${srcs}
@@ -22,4 +24,6 @@ idf_component_register(SRCS ${srcs}
 # Thus, the symbols from this component are not placed in the .map file and
 # hence the constructor, which initialises the encryption scheme for the default
 # NVS partition, never executes. The following is a workaround for the same.
-target_link_libraries(${COMPONENT_LIB} PRIVATE "-u nvs_sec_provider_include_impl")
+if(NOT CONFIG_NVS_SEC_KEY_PROTECT_NONE)
+    target_link_libraries(${COMPONENT_LIB} PRIVATE "-u nvs_sec_provider_include_impl")
+endif()
--- a/components/nvs_sec_provider/Kconfig
+++ b/components/nvs_sec_provider/Kconfig
@@ -4,7 +4,8 @@ menu "NVS Security Provider"
    choice NVS_SEC_KEY_PROTECTION_SCHEME
        prompt "NVS Encryption: Key Protection Scheme"
        depends on NVS_ENCRYPTION
-        default NVS_SEC_KEY_PROTECT_USING_FLASH_ENC
+        default NVS_SEC_KEY_PROTECT_USING_HMAC if SOC_HMAC_SUPPORTED
+        default NVS_SEC_KEY_PROTECT_USING_FLASH_ENC if !SOC_HMAC_SUPPORTED
        help
            This choice defines the default NVS encryption keys protection scheme;
            which will be used for the default NVS partition.
@@ -27,6 +28,12 @@ menu "NVS Security Provider"
                Requires the specified eFuse block (NVS_SEC_HMAC_EFUSE_KEY_ID or the v2 API argument)
                to be empty or pre-written with a key with the purpose ESP_EFUSE_KEY_PURPOSE_HMAC_UP

+        config NVS_SEC_KEY_PROTECT_NONE
+            bool "None"
+            help
+                Select this option if key derivation/protection is handled by
+                a custom implementation, and not by the nvs_sec_provider component.
+
    endchoice

    config NVS_SEC_HMAC_EFUSE_KEY_ID
--- a/components/nvs_sec_provider/nvs_sec_provider.c
+++ b/components/nvs_sec_provider/nvs_sec_provider.c
@@ -291,6 +291,7 @@ esp_err_t nvs_sec_provider_deregister(nvs_sec_scheme_t *sec_scheme_handle)

    free(sec_scheme_handle);

+    nvs_flash_deregister_security_scheme();
    return ESP_OK;
 }

--- a/docs/en/api-reference/storage/nvs_encryption.rst
+++ b/docs/en/api-reference/storage/nvs_encryption.rst
@@ -219,6 +219,9 @@ The component :component:`nvs_sec_provider` stores all the implementation-specif

    This component offers factory functions with which a particular security scheme can be registered without having to worry about the APIs to generate and read the encryption keys (e.g., :cpp:func:`nvs_sec_provider_register_hmac`). Refer to the :example:`security/nvs_encryption_hmac` example for API usage.

+.. note::
+
+    To use a custom implementation for NVS encryption key derivation or protection (instead of the ones provided by the :component:`nvs_sec_provider` component), select the :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_NONE`` configuration option.

 API Reference
 -------------
--- a/docs/en/migration-guides/release-6.x/6.0/security.rst
+++ b/docs/en/migration-guides/release-6.x/6.0/security.rst
@@ -30,3 +30,10 @@ Bootloader Support
 The following deprecated functions have been removed:

 - :cpp:func:`esp_secure_boot_verify_signature_block` – Use :cpp:func:`esp_secure_boot_verify_ecdsa_signature_block` instead.
+
+.. only:: SOC_HMAC_SUPPORTED
+
+    NVS Security Provider
+    ---------------------
+
+    - When NVS encryption is enabled on SoCs with the HMAC peripheral that have flash encryption enabled, the HMAC-based NVS encryption scheme is now selected as default instead of the flash encryption-based scheme. If your application previously used the flash encryption-based scheme, you need to manually configure the NVS encryption scheme to flash encryption from HMAC through ``menuconfig`` or your project's ``sdkconfig`` (i.e., setting ``CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y``).
--- a/docs/zh_CN/api-reference/storage/nvs_encryption.rst
+++ b/docs/zh_CN/api-reference/storage/nvs_encryption.rst
@@ -219,6 +219,9 @@ NVS Security Provider

    该组件通过工厂函数注册了特殊的安全框架，可以实现出厂即用的安全方案。在该方案中，无需使用 API 来生成、读取加密密钥（如 :cpp:func:`nvs_sec_provider_register_hmac`）。要了解 API 的使用，参考示例 :example:`security/nvs_encryption_hmac`。

+.. note::
+
+    如果不希望使用 :component: `nvs_sec_provider` 组件的默认实现，而使用自定义方式生成或者保护 NVS 加密密钥，请选择 :ref:`CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME` -> ``CONFIG_NVS_SEC_KEY_PROTECT_NONE`` 配置项。

 API 参考
 -------------
--- 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
@@ -30,3 +30,10 @@ Mbed TLS
 以下废弃函数已被移除：

 - :cpp:func:`esp_secure_boot_verify_signature_block` – 请使用 :cpp:func:`esp_secure_boot_verify_ecdsa_signature_block` 代替。
+
+.. 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``）。
--- a/examples/security/flash_encryption/sdkconfig.ci
+++ b/examples/security/flash_encryption/sdkconfig.ci
@@ -10,3 +10,4 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/examples/security/flash_encryption/sdkconfig.ci.psram
+++ b/examples/security/flash_encryption/sdkconfig.ci.psram
@@ -7,6 +7,7 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 CONFIG_SPIRAM=y
 CONFIG_SPIRAM_BOOT_INIT=y
--- a/examples/security/flash_encryption/sdkconfig.ci.rom_impl
+++ b/examples/security/flash_encryption/sdkconfig.ci.rom_impl
@@ -7,6 +7,7 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 CONFIG_SPI_FLASH_ROM_IMPL=y
 CONFIG_COMPILER_OPTIMIZATION_SIZE=y
--- a/examples/security/security_features_app/sdkconfig.defaults
+++ b/examples/security/security_features_app/sdkconfig.defaults
@@ -29,3 +29,4 @@ CONFIG_SECURE_FLASH_ENCRYPT_ONLY_IMAGE_LEN_IN_APP_PART=y
 CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP=y
 CONFIG_SECURE_ROM_DL_MODE_ENABLED=y
 CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/examples/system/ota/advanced_https_ota/sdkconfig.ci.anti_rollback
+++ b/examples/system/ota/advanced_https_ota/sdkconfig.ci.anti_rollback
@@ -38,3 +38,4 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
 CONFIG_NVS_ENCRYPTION=n  # this test combination is only for flash encryption and anti-rollback use-case and hence disabling it.
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/examples/system/ota/partitions_ota/sdkconfig.ci.flash_enc_wifi
+++ b/examples/system/ota/partitions_ota/sdkconfig.ci.flash_enc_wifi
@@ -16,6 +16,7 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 # This is required for nvs encryption (which is enabled by default with flash encryption)
 CONFIG_PARTITION_TABLE_OFFSET=0x9000
--- a/examples/system/ota/partitions_ota/sdkconfig.ci.flash_enc_wifi_2
+++ b/examples/system/ota/partitions_ota/sdkconfig.ci.flash_enc_wifi_2
@@ -16,6 +16,7 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 # This is required for nvs encryption (which is enabled by default with flash encryption)
 CONFIG_PARTITION_TABLE_OFFSET=0x9000
--- a/examples/system/ota/partitions_ota/sdkconfig.ci.virt_sb_v2_and_fe
+++ b/examples/system/ota/partitions_ota/sdkconfig.ci.virt_sb_v2_and_fe
@@ -21,3 +21,4 @@ CONFIG_SECURE_BOOT_SIGNING_KEY="test/secure_boot_signing_key.pem"
 CONFIG_SECURE_DISABLE_ROM_DL_MODE=y

 CONFIG_SECURE_FLASH_ENC_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/examples/system/ota/partitions_ota/sdkconfig.ci.virt_sb_v2_and_fe_2
+++ b/examples/system/ota/partitions_ota/sdkconfig.ci.virt_sb_v2_and_fe_2
@@ -24,3 +24,4 @@ CONFIG_SECURE_BOOT_SIGNING_KEY="test/secure_boot_signing_key.pem"
 CONFIG_SECURE_DISABLE_ROM_DL_MODE=y

 CONFIG_SECURE_FLASH_ENC_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/examples/system/ota/simple_ota_example/sdkconfig.ci.flash_enc_wifi
+++ b/examples/system/ota/simple_ota_example/sdkconfig.ci.flash_enc_wifi
@@ -8,6 +8,7 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
 CONFIG_PARTITION_TABLE_OFFSET=0x9000
 CONFIG_EXAMPLE_CONNECT_ETHERNET=n
 CONFIG_EXAMPLE_CONNECT_WIFI=y
--- a/tools/test_apps/build_system/bootloader/sdkconfig.defaults
+++ b/tools/test_apps/build_system/bootloader/sdkconfig.defaults
@@ -15,6 +15,7 @@ CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES=n
 #
 CONFIG_SECURE_FLASH_ENC_ENABLED=y
 CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y

 #
 # Increase partition table offset
--- a/tools/test_apps/security/secure_boot/sdkconfig.ci.04
+++ b/tools/test_apps/security/secure_boot/sdkconfig.ci.04
@@ -3,3 +3,4 @@ CONFIG_SECURE_BOOT=y
 CONFIG_SECURE_BOOT_SIGNING_KEY="test_rsa_3072_key.pem"
 CONFIG_SECURE_FLASH_ENC_ENABLED=y
 CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/tools/test_apps/storage/partition_table_readonly/sdkconfig.ci.encrypted
+++ b/tools/test_apps/storage/partition_table_readonly/sdkconfig.ci.encrypted
@@ -7,3 +7,4 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_DEC=y
 CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=y
 CONFIG_SECURE_FLASH_REQUIRE_ALREADY_ENABLED=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
--- a/tools/test_apps/system/build_test/sdkconfig.ci.flash_encryption_release
+++ b/tools/test_apps/system/build_test/sdkconfig.ci.flash_encryption_release
@@ -1,3 +1,4 @@
 CONFIG_SECURE_FLASH_ENC_ENABLED=y
 CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y
+CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC=y
 CONFIG_PARTITION_TABLE_OFFSET=0xC000