docs: added guide to transit from dev mode to release mode of FE

components/bootloader_support/src/flash_encrypt.c

@@ -69,8 +69,7 @@ void esp_flash_encryption_init_checks()
     mode = esp_get_flash_encryption_mode();
     if (mode == ESP_FLASH_ENC_MODE_DEVELOPMENT) {
 #ifdef CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE
-        ESP_LOGE(TAG, "Flash encryption settings error: app is configured for RELEASE but efuses are set for DEVELOPMENT");
+        ESP_LOGE(TAG, "Flash encryption error: app is set for RELEASE, but efuses are DEVELOPMENT (device is not secure). See Flash Encryption docs to transition.");
-        ESP_LOGE(TAG, "Mismatch found in security options in bootloader menuconfig and efuse settings. Device is not secure.");
 #else
         ESP_LOGW(TAG, "Flash encryption mode is DEVELOPMENT (not secure)");
 #endif // CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE

docs/en/security/flash-encryption.rst

@@ -718,7 +718,9 @@ Release Mode
 
 In release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.
 
-To use this mode, take the following steps:
+If you already enabled flash encryption in Development mode and want to switch to Release mode, see :ref:`flash-enc-transition-dev-to-release`.
+
+To use this mode (first-time enable with Release selected), take the following steps:
 
 1. Ensure that you have an {IDF_TARGET_NAME} device with default flash encryption eFuse settings as shown in :ref:`flash-encryption-efuse`.
 
@@ -760,6 +762,24 @@ For subsequent plaintext field updates, use :ref:`OTA scheme <updating-encrypted
 
     If you have pre-generated the flash encryption key and stored a copy, and the UART download mode is not permanently disabled via :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` {IDF_TARGET_ESP32_V3_ONLY}, then it is possible to update the flash locally by pre-encrypting the files and then flashing the ciphertext. See :ref:`manual-encryption`.
 
+.. _flash-enc-transition-dev-to-release:
+
+Transitioning from Development to Release Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If flash encryption was enabled in :ref:`flash-enc-development-mode`, the device remains in Development mode until the corresponding release eFuses are burned. Selecting **Release mode** in menuconfig (:ref:`CONFIG_SECURE_FLASH_ENCRYPTION_MODE`) only updates the build configuration; it does **not** burn the eFuses.
+To permanently transition the device to Release mode, you must explicitly call :cpp:func:`esp_flash_encryption_set_release_mode` once in your application code to burn the relevant eFuses.
+
+.. code-block:: c
+
+    #include "esp_flash_encrypt.h"
+
+    if (!esp_flash_encryption_cfg_verify_release_mode()) {
+        esp_flash_encryption_set_release_mode();
+    }
+
+Alternatively, refer the :example:`security/security_features_app` example, which implements this logic.
+
 .. _flash-encrypt-best-practices:
 
 Best Practices

docs/en/security/security-features-enablement-workflows.rst

@@ -788,5 +788,3 @@ In this case we generate NVS Encryption keys on a host. This key is then flashed
     The NVS partition (``nvs_encr_partition.bin``) and NVS encryption key (``nvs_encr_key.bin``) can then be flashed to their respective offset using ``esptool``. To see all of the command line options recommended for ``esptool``, check the output print when ``idf.py build`` succeeds.
 
     If Flash Encryption is enabled for the chip, then please encrypt the NVS key partition first before flashing. You may refer the flashing related steps of `Flash Encryption workflow <enable-flash-encryption-externally_>`_.
-
-For a complete example demonstrating the enablement of all security features (Secure Boot v2, flash encryption, NVS encryption, and JTAG with HMAC), see :example:`security/security_features_app`.

docs/zh_CN/security/flash-encryption.rst

@@ -718,7 +718,9 @@ flash 加密设置
 
 在量产模式下，UART 引导加载程序无法执行 flash 加密操作，**只能** 使用 OTA 方案下载新的明文镜像，该方案将在写入 flash 前加密明文镜像。
 
-使用该模式需要执行以下步骤：
+若此前已在开发模式下启用 flash 加密，现需切换至量产模式，请参阅 :ref:`flash-enc-transition-dev-to-release`。
+
+首次启用并选择量产模式时，请按以下步骤操作：
 
 1. 确保你的 {IDF_TARGET_NAME} 设备有 :ref:`flash-encryption-efuse` 中所示的 flash 加密 eFuse 的默认设置。
 
@@ -760,6 +762,24 @@ flash 加密设置
 
     如果用户已经预先生成了 flash 加密密钥并存储了一个副本，并且 UART 下载模式没有通过 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` {IDF_TARGET_ESP32_V3_ONLY} 永久禁用，那么可以通过使用 ``{IDF_TARGET_ENCRYPT_COMMAND}`` 预加密文件，从而在在本地更新 flash，然后烧录密文。请参考 :ref:`manual-encryption`。
 
+.. _flash-enc-transition-dev-to-release:
+
+从开发模式过渡到量产模式
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+若 flash 加密是在 :ref:`flash-enc-development-mode` 下启用的，设备会一直处于开发模式，直到烧录对应的量产模式 eFuse。在 menuconfig 中选择 **量产模式** （:ref:`CONFIG_SECURE_FLASH_ENCRYPTION_MODE`）仅更新构建配置，并 **不会** 烧录 eFuse。
+要将设备永久切换到量产模式，必须在应用程序代码中显式调用一次 :cpp:func:`esp_flash_encryption_set_release_mode` 来烧录相关 eFuse。
+
+.. code-block:: c
+
+    #include "esp_flash_encrypt.h"
+
+    if (!esp_flash_encryption_cfg_verify_release_mode()) {
+        esp_flash_encryption_set_release_mode();
+    }
+
+也可参考 :example:`security/security_features_app` 示例，其已包含上述逻辑。
+
 .. _flash-encrypt-best-practices:
 
 最佳实践

docs/zh_CN/security/security-features-enablement-workflows.rst

@@ -788,5 +788,3 @@ Secure Boot v2 指南
     使用 ``esptool`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool`` 命令行选项。
 
     若芯片启用了 flash 加密，请在烧录前先对 NVS 加密密钥分区进行加密。详情请参阅 `flash 加密工作流程 <enable-flash-encryption-externally_>`_ 中与烧录相关的步骤。
-
-关于同时启用所有安全功能（安全启动 v2、flash 加密、NVS 加密及基于 HMAC 的 JTAG）的完整示例，请参阅 :example:`security/security_features_app`。