From 85b5e6a231d9310358e152807eb711f14336d4ce Mon Sep 17 00:00:00 2001 From: "nilesh.kale" Date: Mon, 23 Mar 2026 11:54:50 +0530 Subject: [PATCH 1/2] fix: added reference to example security/security_features_app in docs --- docs/en/security/secure-boot-v2.rst | 1 + docs/en/security/security-features-enablement-workflows.rst | 2 ++ docs/zh_CN/security/secure-boot-v2.rst | 1 + docs/zh_CN/security/security-features-enablement-workflows.rst | 2 ++ tools/ci/check_examples_documented.py | 2 -- 5 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/en/security/secure-boot-v2.rst b/docs/en/security/secure-boot-v2.rst index 4edba2e0ba..532930fe14 100644 --- a/docs/en/security/secure-boot-v2.rst +++ b/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 ----------------------------------------- diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index b1d87e244d..d60449722d 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -788,3 +788,5 @@ 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 `_. + +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`. diff --git a/docs/zh_CN/security/secure-boot-v2.rst b/docs/zh_CN/security/secure-boot-v2.rst index 8eebce7d97..26b6606164 100644 --- a/docs/zh_CN/security/secure-boot-v2.rst +++ b/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`。 启用安全启动后的限制 -------------------- diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 2773fece36..ecc5582018 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -788,3 +788,5 @@ Secure Boot v2 指南 使用 ``esptool`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool`` 命令行选项。 若芯片启用了 flash 加密，请在烧录前先对 NVS 加密密钥分区进行加密。详情请参阅 `flash 加密工作流程 `_ 中与烧录相关的步骤。 + +关于同时启用所有安全功能（安全启动 v2、flash 加密、NVS 加密及基于 HMAC 的 JTAG）的完整示例，请参阅 :example:`security/security_features_app`。 diff --git a/tools/ci/check_examples_documented.py b/tools/ci/check_examples_documented.py index fa40be81c3..863c5d24bf 100644 --- a/tools/ci/check_examples_documented.py +++ b/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', From f43d0dbadc175ebf93c99ab89e80b87458a306b4 Mon Sep 17 00:00:00 2001 From: "nilesh.kale" Date: Mon, 16 Feb 2026 14:38:58 +0530 Subject: [PATCH 2/2] docs: added guide to transit from dev mode to release mode of FE --- .../bootloader_support/src/flash_encrypt.c | 3 +-- docs/en/security/flash-encryption.rst | 22 ++++++++++++++++++- ...security-features-enablement-workflows.rst | 2 -- docs/zh_CN/security/flash-encryption.rst | 22 ++++++++++++++++++- ...security-features-enablement-workflows.rst | 2 -- 5 files changed, 43 insertions(+), 8 deletions(-) diff --git a/components/bootloader_support/src/flash_encrypt.c b/components/bootloader_support/src/flash_encrypt.c index e3c52b4305..3237e0a5d8 100644 --- a/components/bootloader_support/src/flash_encrypt.c +++ b/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 diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index b7c2d75205..70dc5d36f4 100644 --- a/docs/en/security/flash-encryption.rst +++ b/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 `_. - -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`. diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index e5cf743d6c..fe1cd92dc1 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/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: 最佳实践 diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index ecc5582018..2773fece36 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/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 加密工作流程 `_ 中与烧录相关的步骤。 - -关于同时启用所有安全功能（安全启动 v2、flash 加密、NVS 加密及基于 HMAC 的 JTAG）的完整示例，请参阅 :example:`security/security_features_app`。