Merge branch 'change/secure_boot_config_description_v5.2' into 'release/v5.2'

Improve description of the config SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS (v5.2)

See merge request espressif/esp-idf!38914

components/bootloader/Kconfig.projbuild

@@ -793,6 +793,33 @@ menu "Security features"
             This can lead to permanent bricking of the device, in case all keys are revoked
             because of signature verification failure.
 
+    config SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
+        bool "Do not disable the ability to further read protect eFuses"
+        depends on SECURE_BOOT_V2_ENABLED
+        default n
+        help
+            If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS
+            efuse when Secure Boot is enabled. This prevents any more efuses from being read protected.
+
+            If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure
+            Boot is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and
+            BLOCK4-BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the secure boot public key digest,
+            causing an immediate denial of service and possibly allowing an additional fault injection attack to
+            bypass the signature protection.
+
+            The option must be set when you need to program any read-protected key type into the efuses,
+            e.g., HMAC, ECDSA etc. after secure boot has already been enabled on the device.
+            Please refer to secure boot V2 documentation guide for more details.
+
+            NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block
+
+            NOTE: If "UART ROM download mode (Permanently disabled (recommended))" or
+            "UART ROM download mode (Permanently switch to Secure mode (recommended))" is set,
+            then it is __NOT__ possible to read/write efuses using espefuse.py utility.
+            However, efuse can be read/written from the application
+
+            Please refer to the Secure Boot V2 documentation guide for more information.
+
     config SECURE_BOOT_FLASH_BOOTLOADER_DEFAULT
         bool "Flash bootloader along with other artifacts when using the default flash command"
         depends on SECURE_BOOT_V2_ENABLED && SECURE_BOOT_BUILD_SIGNED_BINARIES
@@ -973,26 +1000,6 @@ menu "Security features"
                 image to this length. It is generally not recommended to set this option, unless you have a legacy
                 partitioning scheme which doesn't support 64KB aligned partition lengths.
 
-        config SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS
-            bool "Allow additional read protecting of efuses"
-            depends on SECURE_BOOT_INSECURE && SECURE_BOOT_V2_ENABLED
-            help
-                If not set (default, recommended), on first boot the bootloader will burn the WR_DIS_RD_DIS
-                efuse when Secure Boot is enabled. This prevents any more efuses from being read protected.
-
-                If this option is set, it will remain possible to write the EFUSE_RD_DIS efuse field after Secure
-                Boot is enabled. This may allow an attacker to read-protect the BLK2 efuse (for ESP32) and
-                BLOCK4-BLOCK10 (i.e. BLOCK_KEY0-BLOCK_KEY5)(for other chips) holding the public key digest, causing an
-                immediate denial of service and possibly allowing an additional fault injection attack to
-                bypass the signature protection.
-
-                NOTE: Once a BLOCK is read-protected, the application will read all zeros from that block
-
-                NOTE: If "UART ROM download mode (Permanently disabled (recommended))" or
-                "UART ROM download mode (Permanently switch to Secure mode (recommended))" is set,
-                then it is __NOT__ possible to read/write efuses using espefuse.py utility.
-                However, efuse can be read/written from the application
-
         config SECURE_BOOT_ALLOW_UNUSED_DIGEST_SLOTS
             bool "Leave unused digest slots available (not revoke)"
             depends on SECURE_BOOT_INSECURE && SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS

docs/en/security/secure-boot-v2.rst

@@ -19,6 +19,8 @@ Secure Boot V2
 
 {IDF_TARGET_SBV2_DEFAULT_SCHEME:default="RSA", esp32c2="ECDSA (V2)"}
 
+{IDF_TARGET_EFUSE_WR_DIS_RD_DIS:default="ESP_EFUSE_WR_DIS_RD_DIS", esp32="ESP_EFUSE_WR_DIS_EFUSE_RD_DISABLE"}
+
 .. important::
 
     This document is about Secure Boot V2, supported on {IDF_TARGET_NAME} {IDF_TARGET_ECO_VERSION}
@@ -413,10 +415,33 @@ Restrictions After Secure Boot Is Enabled
 
 - Any updated bootloader or app will need to be signed with a key matching the digest already stored in eFuse.
 
-- After Secure Boot is enabled, no further eFuses can be read protected. (If :doc:`/security/flash-encryption` is enabled then the bootloader will ensure that any flash encryption key generated on first boot will already be read protected.) If :ref:`CONFIG_SECURE_BOOT_INSECURE` is enabled then this behavior can be disabled, but this is not recommended.
-
 - Please note that enabling Secure Boot or flash encryption disables the USB-OTG USB stack in the ROM, disallowing updates via the serial emulation or Device Firmware Update (DFU) on that port.
 
+Burning read-protected keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After Secure Boot is enabled, no further eFuses can be read-protected, because this might allow an attacker to read-protect the efuse block holding the public key digest, causing an immediate denial of service and possibly allowing an additional fault injection attack to bypass the signature protection.
+
+If :doc:`/security/flash-encryption` is enabled by the 2nd stage bootloader, it ensures that the flash encryption key generated on the first boot shall already be read-protected.
+
+In case you need to read-protect a key after Secure Boot has been enabled on the device, for example,
+
+.. list::
+  :SOC_FLASH_ENC_SUPPORTED:* the flash encryption key
+
+  :SOC_HMAC_SUPPORTED:* HMAC keys
+
+  :SOC_ECDSA_SUPPORTED:* ECDSA keys
+
+  :SOC_KEY_MANAGER_SUPPORTED:* Key Manager keys
+
+  you need to enable the config :ref:`CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS` at the same time when you enable Secure Boot to prevent disabling the ability to read-protect further efuses.
+
+It is highly recommended that all such keys must been burned before enabling secure boot.
+
+In case you need to enable :ref:`CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS`, make sure that you burn the efuse {IDF_TARGET_EFUSE_WR_DIS_RD_DIS}, using ``esp_efuse_write_field_bit()`` API from ``esp_efuse.h``, once all the read-protected efuse keys have been programmed.
+
+
 .. _secure-boot-v2-generate-key:
 
 Generating Secure Boot Signing Key

docs/zh_CN/security/secure-boot-v2.rst

@@ -1 +1 @@
-.. include:: ../../en/security/secure-boot-v2.rst
+.. include:: ../../en/security/secure-boot-v2.rst