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`。