Merge branch 'docs/update_doc_for_fe_dev_mode_to_release_mode_transition' into 'master'

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

Closes IDF-15376

See merge request espressif/esp-idf!45919

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, "Mismatch found in security options in bootloader menuconfig and efuse settings. Device is not secure.");
+        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.");
 #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/secure-boot-v2.rst

@@ -519,6 +519,7 @@ How To Enable Secure Boot v2
 
 11. On subsequent boots, the Secure Boot hardware will verify that the second stage bootloader has not changed, and the second stage bootloader will verify the signed app image using the validated public key portion of its appended signature block.
 
+For a comprehensive example that enables Secure Boot v2 along with other security features such as flash encryption and NVS encryption, see :example:`security/security_features_app`.
 
 Restrictions After Secure Boot Is Enabled
 -----------------------------------------

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/secure-boot-v2.rst

@@ -519,6 +519,7 @@ Secure Boot v2 签名验证也可以在 OTA 更新期间验证数据分区镜像
 
 11. 在后续启动过程中，安全启动硬件会验证二级引导加载程序是否更改，二级引导加载程序会使用其附加的签名块中经验证的公钥部分，验证已签名的应用程序镜像。
 
+关于同时启用安全启动 v2 及其他安全功能（如 flash 加密和 NVS 加密）的完整示例，请参阅 :example:`security/security_features_app`。
 
 启用安全启动后的限制
 --------------------

tools/ci/check_examples_documented.py

@@ -25,8 +25,6 @@ KNOWN_MISSING = {
     'zigbee/esp_zigbee_gateway',
     'zigbee/light_sample/HA_on_off_light',
     'zigbee/light_sample/HA_on_off_switch',
-    # TODO IDF-15376: add :example: reference for security_features_app
-    'security/security_features_app',
     # TODO IDF-15380: add :example: references for bluetooth examples
     'bluetooth/bluedroid/ble/ble_acl_latency/cent',
     'bluetooth/bluedroid/ble/ble_acl_latency/periph',