From e3a34f54538086d20b692699e8143f9864249a86 Mon Sep 17 00:00:00 2001 From: Zheng Zhong Date: Mon, 22 Sep 2025 15:53:04 +0800 Subject: [PATCH 1/3] docs: fix some description in security guide docs --- docs/en/security/flash-encryption.rst | 3 +++ .../security-features-enablement-workflows.rst | 10 +++++++--- docs/en/security/security.rst | 2 +- docs/zh_CN/security/flash-encryption.rst | 3 +++ docs/zh_CN/security/secure-boot-v2.rst | 2 +- .../security-features-enablement-workflows.rst | 10 +++++++--- docs/zh_CN/security/security.rst | 2 +- 7 files changed, 23 insertions(+), 9 deletions(-) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 5ff16ab44d..9a2a1da432 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -510,6 +510,9 @@ If all partitions needs to be updated in encrypted format, run: idf.py encrypted-flash monitor +.. note:: + + The above operations only apply if the `DIS_DOWNLOAD_MANUAL_ENCRYPT` eFuse bit has not been programmed. If this eFuse bit has been programmed, you need to flash the encrypted firmware image instead. .. _flash-enc-release-mode: diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 0a9a796642..42dd47df00 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -318,6 +318,10 @@ In this case all the eFuses related to Flash Encryption are written with help of espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin + .. note:: + + If secure boot is also enabled, please perform the secure boot firmware signing first, and then carry out the above encryption operation. + In the above command, the offsets are used for a sample firmware, and the actual offset for your firmware can be obtained by checking the partition table entry or by running `idf.py partition-table`. Please note that not all the binaries need to be encrypted, the encryption applies only to those generated from the partitions which are marked as ``encrypted`` in the partition table definition file. Other binaries are flashed unencrypted, i.e., as a plain output of the build process. The above files can then be flashed to their respective offset using ``esptool.py``. To see all of the command line options recommended for ``esptool.py``, see the output printed when ``idf.py build`` succeeds. @@ -669,7 +673,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E * CSV file name - In this case, ``sample_singlepage_blob.csv`` is the CSV file which contains the NVS data. Please replace this with the file you wish to choose. - * NVS partition offset - This is the offset at which that NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The offset of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct offset. + * NVS partition size - This is the size at which that NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The size of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct size. 4. Configure the project @@ -718,7 +722,7 @@ In this case we generate NVS Encryption keys on a host. This key is then flashed * CSV file name - In this case `sample_singlepage_blob.csv` is the CSV file which contains the NVS data. Please replace it with the file you wish to choose. - * NVS partition offset - This is the offset at which the NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The offset of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct offset. + * NVS partition size - This is the size at which the NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The size of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct size. 3. Configure the project @@ -729,4 +733,4 @@ 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.py``. To see all of the command line options recommended for ``esptool.py``, check the output print when ``idf.py build`` succeeds. - If Flash Encryption is enabled for the chip, then please encrypt the partition first before flashing. You may refer the flashing related steps of `Flash Encryption workflow `_. + 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 `_. diff --git a/docs/en/security/security.rst b/docs/en/security/security.rst index bc0a5f71ae..49b3989259 100644 --- a/docs/en/security/security.rst +++ b/docs/en/security/security.rst @@ -75,7 +75,7 @@ Please refer to :doc:`flash-encryption` for detailed information about this feat Flash Encryption Best Practices ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* It is recommended to use flash Encryption release mode for the production use-cases. +* It is recommended to use :ref:`flash-enc-release-mode` for the production use-cases. * It is recommended to have a unique flash encryption key per device. * Enable :ref:`secure_boot-guide` as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot. diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index 37771c4c63..01cf0c7e33 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -510,6 +510,9 @@ flash 加密设置 idf.py encrypted-flash monitor +.. note:: + + 上述操作仅适用于 DIS_DOWNLOAD_MANUAL_ENCRYPT eFuse 位未被烧录的情况。如果该 eFuse 位已被烧录，则需要烧录加密后的密文镜像。 .. _flash-enc-release-mode: diff --git a/docs/zh_CN/security/secure-boot-v2.rst b/docs/zh_CN/security/secure-boot-v2.rst index 202322dffb..5635137921 100644 --- a/docs/zh_CN/security/secure-boot-v2.rst +++ b/docs/zh_CN/security/secure-boot-v2.rst @@ -128,7 +128,7 @@ 5. 引导加载程序验证应用程序镜像的签名块，请参阅 :ref:`verify_signature-block`。如果验证失败，启动过程将中止。 -6. 引导加载程序使用原始镜像数据、相应的签名块以及 eFuse 验证引导加载程序镜像，请参阅 :ref:`verify_image`。如果验证失败，启动过程将中止。如果验证失败，但发现了其他应用程序镜像，引导加载程序将使用步骤 5 到 7 验证另一个镜像。该过程将重复，直至找到有效镜像，或所有镜像验证完毕。 +6. 引导加载程序使用原始镜像数据、相应的签名块以及 eFuse 验证应用程序镜像，请参阅 :ref:`verify_image`。如果验证失败，启动过程将中止。如果验证失败，但发现了其他应用程序镜像，引导加载程序将使用步骤 5 到 7 验证另一个镜像。该过程将重复，直至找到有效镜像，或所有镜像验证完毕。 7. 引导加载程序执行经验证的应用程序镜像。 diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 9e2ec82a03..995a5bb532 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -318,6 +318,10 @@ espsecure.py encrypt_flash_data {IDF_TARGET_FLASH_ENC_ARGS} --keyfile my_flash_encryption_key.bin --address 0x10000 --output my-app-enc.bin build/my-app.bin + .. note:: + + 如同时开启了 secure boot，请先 secure boot 签名固件后再做上述加密操作。 + 上述命令中的偏移量仅适用于示例固件，请通过检查分区表条目或运行 `idf.py partition-table` 来获取你固件的实际偏移量。请注意，不需要加密所有二进制文件，只需加密在分区表定义文件中带有 ``encrypted`` 标记的文件，其他二进制文件只作为构建过程的普通输出进行烧录。 使用 ``esptool.py`` 可以将上述文件烧写到各自的偏移地址。要查看所有推荐的 ``esptool.py`` 命令行选项，请查阅 ``idf.py build`` 构建成功后打印的输出。 @@ -669,7 +673,7 @@ Secure Boot v2 指南 * CSV 文件名 - 此命令中，``sample_singlepage_blob.csv`` 是指包含 NVS 数据的 CSV 文件，请将其替换为所选择的文件。 - * NVS 分区偏移量 - 这是 {IDF_TARGET_NAME} flash 中存储 NVS 分区的偏移地址。通过在项目目录下执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区偏移地址。请将上述命令中的示例值 ``0x3000`` 调整为正确的偏移量。 + * NVS 分区大小 - 这是 {IDF_TARGET_NAME} flash 中存储 NVS 分区的大小。通过在项目目录下执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区大小。请将上述命令中的示例值 ``0x3000`` 调整为正确的大小。 4. 配置项目 @@ -718,7 +722,7 @@ Secure Boot v2 指南 * CSV 文件名 - 上述命名中的 `sample_singlepage_blob.csv` 是指包含 NVS 数据的 CSV 文件，请将其替换为所选文件。 - * NVS 分区偏移量 - 这是 NVS 分区在 {IDF_TARGET_NAME} 的 flash 中存储时的偏移地址。在项目目录中执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区的偏移量。请将上述命令中的示例值 ``0x3000`` 替换为正确的偏移量。 + * NVS 分区大小 - 这是 NVS 分区在 {IDF_TARGET_NAME} 的 flash 中存储时的偏移大小。在项目目录中执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区的大小。请将上述命令中的示例值 ``0x3000`` 替换为正确的大小。 3. 配置项目 @@ -729,4 +733,4 @@ Secure Boot v2 指南 使用 ``esptool.py`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool.py`` 命令行选项。 - 若芯片启用了 flash 加密，请在烧录之前先加密分区。详情请参阅 `flash 加密工作流程 `_ 中与烧录相关的步骤。 + 若芯片启用了 flash 加密，请在烧录之前先加密 NVS 加密秘钥分区。详情请参阅 `flash 加密工作流程 `_ 中与烧录相关的步骤。 diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst index 6bdbfcec1b..3037e4dc64 100644 --- a/docs/zh_CN/security/security.rst +++ b/docs/zh_CN/security/security.rst @@ -75,7 +75,7 @@ flash 加密功能可以加密外部 flash 中的内容，从而保护存储在 flash 加密最佳实践 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* 建议在生产环境中使用 flash 加密的发布模式。 +* 建议在生产环境中使用 flash 加密的 :ref:`flash-enc-release-mode`。 * 建议为每个设备生成唯一的 flash 加密密钥。 * 启用 :ref:`secure_boot-guide` 作为额外保护层，防止 flash 在启动前遭受恶意攻击。 From a4e05f49c0f319f8eaa3d0aaeb6dfd484ac97b52 Mon Sep 17 00:00:00 2001 From: Zheng Zhong Date: Mon, 22 Sep 2025 09:59:54 +0000 Subject: [PATCH 2/3] fix : apply the suggestion from doc team --- docs/en/security/flash-encryption.rst | 2 +- docs/en/security/security-features-enablement-workflows.rst | 2 +- docs/zh_CN/security/flash-encryption.rst | 2 +- .../zh_CN/security/security-features-enablement-workflows.rst | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 9a2a1da432..4606cbaa75 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -512,7 +512,7 @@ If all partitions needs to be updated in encrypted format, run: .. note:: - The above operations only apply if the `DIS_DOWNLOAD_MANUAL_ENCRYPT` eFuse bit has not been programmed. If this eFuse bit has been programmed, you need to flash the encrypted firmware image instead. + The above operations are only applicable when the ``DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit has not been programmed. If this eFuse bit has been programmed, you must flash the pre-encrypted ciphertext image instead. .. _flash-enc-release-mode: diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 42dd47df00..8e94beb022 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -320,7 +320,7 @@ In this case all the eFuses related to Flash Encryption are written with help of .. note:: - If secure boot is also enabled, please perform the secure boot firmware signing first, and then carry out the above encryption operation. + If secure boot is enabled, perform secure boot signing of the firmware before carrying out the above encryption operation. In the above command, the offsets are used for a sample firmware, and the actual offset for your firmware can be obtained by checking the partition table entry or by running `idf.py partition-table`. Please note that not all the binaries need to be encrypted, the encryption applies only to those generated from the partitions which are marked as ``encrypted`` in the partition table definition file. Other binaries are flashed unencrypted, i.e., as a plain output of the build process. diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index 01cf0c7e33..ba48561907 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -512,7 +512,7 @@ flash 加密设置 .. note:: - 上述操作仅适用于 DIS_DOWNLOAD_MANUAL_ENCRYPT eFuse 位未被烧录的情况。如果该 eFuse 位已被烧录，则需要烧录加密后的密文镜像。 + 上述操作仅适用于 ``DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位未被烧录的情况。如果该 eFuse 位已被烧录，则需要烧录加密后的密文镜像。 .. _flash-enc-release-mode: diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 995a5bb532..3a92be5a55 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -320,7 +320,7 @@ .. note:: - 如同时开启了 secure boot，请先 secure boot 签名固件后再做上述加密操作。 + 如果同时启用了安全启动功能，请先对固件进行安全启动签名，再执行上述加密操作。 上述命令中的偏移量仅适用于示例固件，请通过检查分区表条目或运行 `idf.py partition-table` 来获取你固件的实际偏移量。请注意，不需要加密所有二进制文件，只需加密在分区表定义文件中带有 ``encrypted`` 标记的文件，其他二进制文件只作为构建过程的普通输出进行烧录。 @@ -733,4 +733,4 @@ Secure Boot v2 指南 使用 ``esptool.py`` 命令，将 NVS 分区 (``nvs_encr_partition.bin``) 和 NVS 加密密钥 (``nvs_encr_key.bin``) 烧录到各自的偏移地址。通过 ``idf.py build`` 成功后打印的输出，可查看所有推荐的 ``esptool.py`` 命令行选项。 - 若芯片启用了 flash 加密，请在烧录之前先加密 NVS 加密秘钥分区。详情请参阅 `flash 加密工作流程 `_ 中与烧录相关的步骤。 + 若芯片启用了 flash 加密，请在烧录前先对 NVS 加密密钥分区进行加密。详情请参阅 `flash 加密工作流程 `_ 中与烧录相关的步骤。 From 7514c17c769edf75b10279481d3bc8906af9c684 Mon Sep 17 00:00:00 2001 From: Zhang Shuxian Date: Thu, 27 Nov 2025 11:12:45 +0800 Subject: [PATCH 3/3] docs: implement comments --- docs/en/security/security-features-enablement-workflows.rst | 4 ++-- .../zh_CN/security/security-features-enablement-workflows.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 8e94beb022..062f9df92d 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -673,7 +673,7 @@ The details about NVS encryption and related schemes can be found at :doc:`NVS E * CSV file name - In this case, ``sample_singlepage_blob.csv`` is the CSV file which contains the NVS data. Please replace this with the file you wish to choose. - * NVS partition size - This is the size at which that NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The size of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct size. + * NVS partition size - This is the size of the NVS partition in bytes. Please update the sample value of ``0x3000`` in the above-provided command to the correct size of your NVS partition. 4. Configure the project @@ -722,7 +722,7 @@ In this case we generate NVS Encryption keys on a host. This key is then flashed * CSV file name - In this case `sample_singlepage_blob.csv` is the CSV file which contains the NVS data. Please replace it with the file you wish to choose. - * NVS partition size - This is the size at which the NVS partition shall be stored in the flash of {IDF_TARGET_NAME}. The size of your NVS partition can be found by executing ``idf.py partition-table`` in the projtect directory. Please update the sample value of ``0x3000`` in the above-provided command to the correct size. + * NVS partition size - This is the size of the NVS partition in bytes. Please update the sample value of ``0x3000`` in the above-provided command to the correct size of your NVS partition. 3. Configure the project diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 3a92be5a55..e91b975bff 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -673,7 +673,7 @@ Secure Boot v2 指南 * CSV 文件名 - 此命令中，``sample_singlepage_blob.csv`` 是指包含 NVS 数据的 CSV 文件，请将其替换为所选择的文件。 - * NVS 分区大小 - 这是 {IDF_TARGET_NAME} flash 中存储 NVS 分区的大小。通过在项目目录下执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区大小。请将上述命令中的示例值 ``0x3000`` 调整为正确的大小。 + * NVS 分区大小 - 这是 NVS 分区的大小（以字节为单位）。请将上述命令中的示例值 ``0x3000`` 更新为你实际 NVS 分区的正确大小。 4. 配置项目 @@ -722,7 +722,7 @@ Secure Boot v2 指南 * CSV 文件名 - 上述命名中的 `sample_singlepage_blob.csv` 是指包含 NVS 数据的 CSV 文件，请将其替换为所选文件。 - * NVS 分区大小 - 这是 NVS 分区在 {IDF_TARGET_NAME} 的 flash 中存储时的偏移大小。在项目目录中执行 ``idf.py partition-table`` 命令，可以找到 NVS 分区的大小。请将上述命令中的示例值 ``0x3000`` 替换为正确的大小。 + * NVS 分区大小 - 这是 NVS 分区的大小（以字节为单位）。请将上述命令中的示例值 ``0x3000`` 更新为你实际 NVS 分区的正确大小。 3. 配置项目