Merge branch 'docs/fix_some_expressions_in_security_guide_v5.4' into 'release/v5.4'

docs: fix some description in security guide docs (v5.4)

See merge request espressif/esp-idf!43819

Author: AdityaHPatwardhan

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 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:
 

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 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.
 
     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 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
 
@@ -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 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
 
@@ -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 <enable-flash-encryption-externally_>`_.
+    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_>`_.

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.
 

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:
 

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. 引导加载程序执行经验证的应用程序镜像。
 

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::
+
+        如果同时启用了安全启动功能，请先对固件进行安全启动签名，再执行上述加密操作。
+
     上述命令中的偏移量仅适用于示例固件，请通过检查分区表条目或运行 `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 分区大小 - 这是 NVS 分区的大小（以字节为单位）。请将上述命令中的示例值 ``0x3000`` 更新为你实际 NVS 分区的正确大小。
 
     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 分区的大小（以字节为单位）。请将上述命令中的示例值 ``0x3000`` 更新为你实际 NVS 分区的正确大小。
 
 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 加密工作流程 <enable-flash-encryption-externally_>`_ 中与烧录相关的步骤。
+    若芯片启用了 flash 加密，请在烧录前先对 NVS 加密密钥分区进行加密。详情请参阅 `flash 加密工作流程 <enable-flash-encryption-externally_>`_ 中与烧录相关的步骤。

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 在启动前遭受恶意攻击。