From d6c11846766c92a40a1d1262659fc718b7463f1f Mon Sep 17 00:00:00 2001 From: "harshal.patil" Date: Fri, 19 Sep 2025 13:01:32 +0530 Subject: [PATCH 1/3] fix(bootloader_support): Reorder write protection bits of some shared security efuses --- components/bootloader/Kconfig.projbuild | 25 +++++++++++++++++++ .../src/esp32c5/secure_boot_secure_features.c | 2 -- .../bootloader_support/src/secure_boot.c | 8 ++++++ components/esp_security/Kconfig | 10 ++++++-- components/esp_security/src/init.c | 25 ++++++++++++++++--- docs/en/security/flash-encryption.rst | 4 +++ ...security-features-enablement-workflows.rst | 3 +-- 7 files changed, 68 insertions(+), 9 deletions(-) diff --git a/components/bootloader/Kconfig.projbuild b/components/bootloader/Kconfig.projbuild index 19e5108f85..4e080668af 100644 --- a/components/bootloader/Kconfig.projbuild +++ b/components/bootloader/Kconfig.projbuild @@ -972,6 +972,24 @@ menu "Security features" so that the bootloader would not need to enable secure boot and thus you could avoid its revocation strategy. + config SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA + bool "Skip write-protection of SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH" + default y if SECURE_FLASH_PSEUDO_ROUND_FUNC + default n + depends on SOC_ECDSA_SUPPORT_CURVE_P384 && SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND + help + If not set (default, recommended), on the first boot when Secure Boot is enabled for + targets that support Secure Boot using ECDSA-P384, the bootloader will burn the write-protection bit of + of SECURE_BOOT_SHA384_EN that could be shared by multiple other efuse bits like + SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH / XTS_DPA_PSEUDO_LEVEL. + + Once this efuse bit is write-protected you cannot update the values of the shared efuses, for example, + the security strength value of XTS_DPA_PSEUDO_LEVEL or setting ECC_FORCE_CONST_TIME. + + List of eFuses with the same write protection bit: + + ESP32-C5: XTS_DPA_PSEUDO_LEVEL and ECC_FORCE_CONST_TIME + config SECURE_FLASH_UART_BOOTLOADER_ALLOW_ENC bool "Leave UART bootloader encryption enabled" depends on SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT @@ -1055,6 +1073,7 @@ menu "Security features" ESP32-S3: DIS_ICACHE, DIS_DCACHE, DIS_DOWNLOAD_ICACHE, DIS_DOWNLOAD_DCACHE, DIS_FORCE_DOWNLOAD, DIS_USB_OTG, DIS_TWAI, DIS_APP_CPU, DIS_PAD_JTAG, DIS_DOWNLOAD_MANUAL_ENCRYPT, DIS_USB_JTAG, DIS_USB_SERIAL_JTAG, STRAP_JTAG_SEL, USB_PHY_SEL. + endmenu # Potentially Insecure config SECURE_FLASH_ENCRYPT_ONLY_IMAGE_LEN_IN_APP_PART @@ -1101,6 +1120,12 @@ menu "Security features" The strength of the pseudo rounds functions can be configured to low, medium and high, each denoting the values that would be stored in the efuses field. By default the value to set to low. + + It is recommended that the required strength of the pseudo rounds function should be set during the + first boot itself. If your workflow needs to update the function's strength after the first boot, + you should enable CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA to avoid write protecting this + bit during the boot up for targets that support Secure Boot using ECDSA-P384. + You can configure the strength of the pseudo rounds functions according to your use cases, for example, increasing the strength would provide higher security but would slow down the flash encryption/decryption operations. diff --git a/components/bootloader_support/src/esp32c5/secure_boot_secure_features.c b/components/bootloader_support/src/esp32c5/secure_boot_secure_features.c index 5da95e3528..cc9f57b766 100644 --- a/components/bootloader_support/src/esp32c5/secure_boot_secure_features.c +++ b/components/bootloader_support/src/esp32c5/secure_boot_secure_features.c @@ -53,8 +53,6 @@ esp_err_t esp_secure_boot_enable_secure_features(void) esp_efuse_write_field_bit(ESP_EFUSE_SECURE_BOOT_SHA384_EN); #endif - esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_SECURE_BOOT_SHA384_EN); - esp_efuse_write_field_bit(ESP_EFUSE_SECURE_BOOT_EN); #ifndef CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS diff --git a/components/bootloader_support/src/secure_boot.c b/components/bootloader_support/src/secure_boot.c index a7d566e8fd..05ab0694eb 100644 --- a/components/bootloader_support/src/secure_boot.c +++ b/components/bootloader_support/src/secure_boot.c @@ -429,6 +429,13 @@ bool esp_secure_boot_cfg_verify_release_mode(void) } #if SOC_ECDSA_SUPPORT_CURVE_P384 +#if CONFIG_SECURE_BOOT_ECDSA_KEY_LEN_384_BITS + secure = esp_efuse_read_field_bit(ESP_EFUSE_SECURE_BOOT_SHA384_EN); + result &= secure; + if (!secure) { + ESP_LOGW(TAG, "Not enabled Secure Boot using SHA-384 mode (set SECURE_BOOT_SHA384_EN->1)"); + } +#else /* When using Secure Boot with SHA-384, the efuse bit representing Secure Boot with SHA-384 would already be programmed. * But in the case of the existing Secure Boot V2 schemes using SHA-256, the efuse bit representing * Secure Boot with SHA-384 needs to be write-protected, so that an attacker cannot perform a denial-of-service @@ -439,6 +446,7 @@ bool esp_secure_boot_cfg_verify_release_mode(void) if (!secure) { ESP_LOGW(TAG, "Not write-protected secure boot using SHA-384 mode (set WR_DIS_SECURE_BOOT_SHA384_EN->1)"); } +#endif #endif secure = (num_keys != 0); diff --git a/components/esp_security/Kconfig b/components/esp_security/Kconfig index 50d0caf4ea..feadfe56a2 100644 --- a/components/esp_security/Kconfig +++ b/components/esp_security/Kconfig @@ -40,7 +40,7 @@ menu "ESP Security Specific" config ESP_CRYPTO_FORCE_ECC_CONSTANT_TIME_POINT_MUL bool "Forcefully enable ECC constant time point multiplication operations" depends on SOC_ECC_CONSTANT_TIME_POINT_MUL - default N + default n help If enabled, the app startup code will burn the ECC_FORCE_CONST_TIME efuse bit to force the ECC peripheral to always perform constant time point multiplication operations, @@ -51,10 +51,16 @@ menu "ESP Security Specific" time point multiplication operations by changing the default ESP-IDF configurations. Performing constant time operations protect the ECC multiplication operations from timing attacks. + For targets that support Secure Boot using ECDSA-P384, the write-protection bit of the efuse + bit could be shared by multiple other efuse bits and can be programmed by the application when + Secure Boot is enabled. + Thus, you could select CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA, in case you would like + to skip the write-protection of the efuse bit. + config ESP_ECDSA_ENABLE_P192_CURVE bool "Enable ECDSA 192-curve operations" depends on SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED - default N + default n help By default, only the 256-bit curve operations are allowed. If this configuration is enabled, it will set the eFuse to allow ECDSA operations using both the 192-bit and 256-bit curves. diff --git a/components/esp_security/src/init.c b/components/esp_security/src/init.c index 14ede2dc0d..56e812c4cf 100644 --- a/components/esp_security/src/init.c +++ b/components/esp_security/src/init.c @@ -46,6 +46,8 @@ ESP_SYSTEM_INIT_FN(esp_security_init, SECONDARY, BIT(0), 103) esp_crypto_dpa_protection_startup(); #endif + esp_err_t err = ESP_FAIL; + #if CONFIG_ESP_CRYPTO_FORCE_ECC_CONSTANT_TIME_POINT_MUL bool force_constant_time = true; #if CONFIG_IDF_TARGET_ESP32H2 @@ -55,7 +57,7 @@ ESP_SYSTEM_INIT_FN(esp_security_init, SECONDARY, BIT(0), 103) #endif if (!esp_efuse_read_field_bit(ESP_EFUSE_ECC_FORCE_CONST_TIME) && force_constant_time) { ESP_EARLY_LOGD(TAG, "Forcefully enabling ECC constant time operations"); - esp_err_t err = esp_efuse_write_field_bit(ESP_EFUSE_ECC_FORCE_CONST_TIME); + err = esp_efuse_write_field_bit(ESP_EFUSE_ECC_FORCE_CONST_TIME); if (err != ESP_OK) { ESP_EARLY_LOGE(TAG, "Enabling ECC constant time operations forcefully failed."); return err; @@ -64,13 +66,30 @@ ESP_SYSTEM_INIT_FN(esp_security_init, SECONDARY, BIT(0), 103) #endif #if CONFIG_ESP_ECDSA_ENABLE_P192_CURVE - esp_err_t err = esp_efuse_enable_ecdsa_p192_curve_mode(); + err = esp_efuse_enable_ecdsa_p192_curve_mode(); if (err != ESP_OK) { return err; } #endif - return ESP_OK; +#if CONFIG_SECURE_BOOT_V2_ENABLED +#if !CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA +// C5 +#if SOC_ECDSA_SUPPORT_CURVE_P384 && !CONFIG_SECURE_BOOT_ECDSA_KEY_LEN_384_BITS + // Since SECURE_BOOT_SHA384_EN, XTS_DPA_PSEUDO_LEVEL, and ECC_FORCE_CONST_TIME share the + // same write-protection bit, these efuses should only be write-protected after all of + // them have been programmed. + err = esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_SECURE_BOOT_SHA384_EN); + if (err != ESP_OK) { + ESP_LOGE(TAG, "Failed to write protect the SECURE_BOOT_SHA384_EN efuse bit."); + return err; + } +#endif +#endif +#endif + + err = ESP_OK; + return err; } void esp_security_init_include_impl(void) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 7685295383..30f81513cb 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -876,6 +876,10 @@ It is recommended to use flash encryption in combination with Secure Boot. Howev - :ref:`Re-flashing via Pregenerated Flash Encryption Key ` is still possible, provided the bootloader is not re-flashed. Re-flashing the bootloader requires the same :ref:`Re-flashable ` option to be enabled in the Secure Boot config. +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND and SOC_ECDSA_SUPPORT_CURVE_P384 + + - It is recommended that the required :ref: `strength of the pseudo rounds function ` should be set during the first boot itself when flash encryption release mode is enabled. If your workflow needs to update the function's strength after the first boot, you should enable :ref:`CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA` to avoid write protecting this bit during the boot up. + .. _flash-encryption-advanced-features: Advanced Features diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 01b579517d..2dd5283e05 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -500,8 +500,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG. :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently. :SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details. - :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit. - :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 secure boot eFuse bit. + :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 secure boot eFuse bit (As this write protection bit is shared with XTS_DPA_PSEUDO_LEVEL and ECC_FORCE_CONST_TIME, it is recommended to write protect this bit only after configuring all the other shared efuses). The respective eFuses can be burned by running: From 5aa5366e7fd29aeb19abb25ef00ef847baa64fa1 Mon Sep 17 00:00:00 2001 From: "harshal.patil" Date: Mon, 1 Sep 2025 15:44:29 +0530 Subject: [PATCH 2/3] fix(bootloader_support): Reorder write disabling ECDSA_CURVE_MODE --- .../src/esp32h2/secure_boot_secure_features.c | 6 ------ .../src/esp32h21/secure_boot_secure_features.c | 4 ---- components/esp_security/src/init.c | 16 ++++++++++++++++ .../security-features-enablement-workflows.rst | 1 + 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/components/bootloader_support/src/esp32h2/secure_boot_secure_features.c b/components/bootloader_support/src/esp32h2/secure_boot_secure_features.c index cb1f69f8cf..9798c7e73b 100644 --- a/components/bootloader_support/src/esp32h2/secure_boot_secure_features.c +++ b/components/bootloader_support/src/esp32h2/secure_boot_secure_features.c @@ -37,12 +37,6 @@ esp_err_t esp_secure_boot_enable_secure_features(void) ESP_LOGW(TAG, "UART ROM Download mode kept enabled - SECURITY COMPROMISED"); #endif -#ifdef SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED - if (ecdsa_ll_is_configurable_curve_supported()) { - esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_ECDSA_CURVE_MODE); - } -#endif - #ifndef CONFIG_SECURE_BOOT_ALLOW_JTAG ESP_LOGI(TAG, "Disable hardware & software JTAG..."); esp_efuse_write_field_bit(ESP_EFUSE_DIS_PAD_JTAG); diff --git a/components/bootloader_support/src/esp32h21/secure_boot_secure_features.c b/components/bootloader_support/src/esp32h21/secure_boot_secure_features.c index 86b501cc20..a63f05d6c6 100644 --- a/components/bootloader_support/src/esp32h21/secure_boot_secure_features.c +++ b/components/bootloader_support/src/esp32h21/secure_boot_secure_features.c @@ -36,10 +36,6 @@ esp_err_t esp_secure_boot_enable_secure_features(void) ESP_LOGW(TAG, "UART ROM Download mode kept enabled - SECURITY COMPROMISED"); #endif -#ifdef SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED - esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_ECDSA_CURVE_MODE); -#endif - #ifndef CONFIG_SECURE_BOOT_ALLOW_JTAG ESP_LOGI(TAG, "Disable hardware & software JTAG..."); esp_efuse_write_field_bit(ESP_EFUSE_DIS_PAD_JTAG); diff --git a/components/esp_security/src/init.c b/components/esp_security/src/init.c index 56e812c4cf..e133b5a890 100644 --- a/components/esp_security/src/init.c +++ b/components/esp_security/src/init.c @@ -22,6 +22,10 @@ #include "hal/key_mgr_ll.h" #endif /* SOC_KEY_MANAGER_SUPPORT_KEY_DEPLOYMENT */ +#if SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED +#include "hal/ecdsa_ll.h" +#endif /* SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED */ + __attribute__((unused)) static const char *TAG = "esp_security"; static void esp_key_mgr_init(void) @@ -73,6 +77,18 @@ ESP_SYSTEM_INIT_FN(esp_security_init, SECONDARY, BIT(0), 103) #endif #if CONFIG_SECURE_BOOT_V2_ENABLED +// H2, H21 +#if SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED + // Also write protects the ECDSA_CURVE_MODE efuse bit. + if (ecdsa_ll_is_configurable_curve_supported()) { + err = esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_ECDSA_CURVE_MODE); + if (err != ESP_OK) { + ESP_LOGE(TAG, "Failed to write protect the ECDSA_CURVE_MODE efuse bit."); + return err; + } + } +#endif + #if !CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA // C5 #if SOC_ECDSA_SUPPORT_CURVE_P384 && !CONFIG_SECURE_BOOT_ECDSA_KEY_LEN_384_BITS diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 2dd5283e05..410ca426aa 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -500,6 +500,7 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG. :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently. :SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details. + :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit (As this write protection bit is shared with ECC_FORCE_CONST_TIME, it is recommended to write protect this bit only after configuring the ECC_FORCE_CONST_TIME efuse). :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 secure boot eFuse bit (As this write protection bit is shared with XTS_DPA_PSEUDO_LEVEL and ECC_FORCE_CONST_TIME, it is recommended to write protect this bit only after configuring all the other shared efuses). The respective eFuses can be burned by running: From 71f84057423b5449b91b72e88b9dbbd803cccf39 Mon Sep 17 00:00:00 2001 From: Shen Mengjing Date: Fri, 12 Sep 2025 19:09:50 +0800 Subject: [PATCH 3/3] docs: Add the updated CN translation --- docs/en/security/flash-encryption.rst | 2 +- ...security-features-enablement-workflows.rst | 4 ++-- docs/zh_CN/security/flash-encryption.rst | 22 +++++++++++-------- ...security-features-enablement-workflows.rst | 14 ++++++------ docs/zh_CN/security/security.rst | 2 +- 5 files changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 30f81513cb..efe90e745c 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -878,7 +878,7 @@ It is recommended to use flash encryption in combination with Secure Boot. Howev .. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND and SOC_ECDSA_SUPPORT_CURVE_P384 - - It is recommended that the required :ref: `strength of the pseudo rounds function ` should be set during the first boot itself when flash encryption release mode is enabled. If your workflow needs to update the function's strength after the first boot, you should enable :ref:`CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA` to avoid write protecting this bit during the boot up. + - It is recommended that the required strength of the :ref:`xts-aes-pseudo-round-func` should be set during the first boot when flash encryption release mode is enabled. If your workflow needs to update the function's strength after the first boot, you should enable :ref:`CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA` to avoid write-protecting this bit during boot. .. _flash-encryption-advanced-features: diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst index 410ca426aa..51d587cfb1 100644 --- a/docs/en/security/security-features-enablement-workflows.rst +++ b/docs/en/security/security-features-enablement-workflows.rst @@ -500,8 +500,8 @@ In this workflow we shall use ``espsecure`` tool to generate signing keys and us :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``: Disable USB switch to JTAG. :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``: Disable JTAG permanently. :SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``: Aggressive revocation of key digests, see :ref:`secure-boot-v2-aggressive-key-revocation` for more details. - :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit (As this write protection bit is shared with ECC_FORCE_CONST_TIME, it is recommended to write protect this bit only after configuring the ECC_FORCE_CONST_TIME efuse). - :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 secure boot eFuse bit (As this write protection bit is shared with XTS_DPA_PSEUDO_LEVEL and ECC_FORCE_CONST_TIME, it is recommended to write protect this bit only after configuring all the other shared efuses). + :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``: Disable writing to the ECDSA curve mode eFuse bit. As this write protection bit is shared with ``ECC_FORCE_CONST_TIME``, it is recommended to write protect this bit only after configuring the ``ECC_FORCE_CONST_TIME`` eFuse. + :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``: Disable writing to the SHA-384 Secure Boot eFuse bit. As this write protection bit is shared with ``XTS_DPA_PSEUDO_LEVEL`` and ``ECC_FORCE_CONST_TIME``, it is recommended to write protect this bit only after configuring all the other shared eFuses. The respective eFuses can be burned by running: diff --git a/docs/zh_CN/security/flash-encryption.rst b/docs/zh_CN/security/flash-encryption.rst index a1bee0d6bf..fb57142778 100644 --- a/docs/zh_CN/security/flash-encryption.rst +++ b/docs/zh_CN/security/flash-encryption.rst @@ -490,7 +490,7 @@ flash 加密设置 如果使用开发模式，那么更新和重新烧录二进制文件最简单的方法是 :ref:`encrypt-partitions`。 -如果使用发布模式，那么可以在主机上预先加密二进制文件，然后将其作为密文烧录。具体请参考 :ref:`manual-encryption`。 +如果使用量产模式，那么可以在主机上预先加密二进制文件，然后将其作为密文烧录。具体请参考 :ref:`manual-encryption`。 .. _encrypt-partitions: @@ -513,10 +513,10 @@ flash 加密设置 .. _flash-enc-release-mode: -发布模式 +量产模式 ^^^^^^^^^^ -在发布模式下，UART 引导加载程序无法执行 flash 加密操作，**只能** 使用 OTA 方案下载新的明文镜像，该方案将在写入 flash 前加密明文镜像。 +在量产模式下，UART 引导加载程序无法执行 flash 加密操作，**只能** 使用 OTA 方案下载新的明文镜像，该方案将在写入 flash 前加密明文镜像。 使用该模式需要执行以下步骤： @@ -529,9 +529,9 @@ flash 加密设置 .. list:: - :ref:`启动时使能 flash 加密 `。 - :esp32: - :ref:`选择发布模式 `。（注意一旦选择了发布模式，``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件） + :esp32: - :ref:`选择量产模式 `。（注意一旦选择了量产模式，``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件） :esp32: - :ref:`选择 UART ROM 下载模式（推荐永久性禁用）` （注意该选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 级别设置为 3 时 (ESP32 V3) 可用。）默认选项是保持启用 UART ROM 下载模式，然而建议永久禁用该模式，以减少攻击者可用的选项。 - :not esp32: - :ref:`选择发布模式 `。（注意一旦选择了发布模式，``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件） + :not esp32: - :ref:`选择量产模式 `。（注意一旦选择了量产模式，``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位将被编程为在 ROM 下载模式下禁用 flash 加密硬件） :not esp32: - :ref:`选择 UART ROM 下载（推荐永久性的切换到安全模式）`。这是默认且推荐使用的选项。如果不需要该模式，也可以改变此配置设置永久地禁用 UART ROM 下载模式。 :SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - :ref:`启用 XTS-AES 伪轮次功能 `。该选项已默认启用，且配置为最低强度等级，以降低对 flash 加密/解密操作的性能影响。如需了解每个安全等级对性能影响的更多信息，请参考 :ref:`xts-aes-pseudo-round-func`。 - :ref:`选择适当详细程度的引导加载程序日志级别 `。 @@ -552,7 +552,7 @@ flash 加密设置 该命令将向 flash 写入未加密的镜像：二级引导加载程序、分区表和应用程序。烧录完成后，{IDF_TARGET_NAME} 将复位。在下一次启动时，二级引导加载程序会加密：二级引导加载程序、应用程序分区和标记为 ``加密`` 的分区，然后复位。就地加密可能需要时间，对于大的分区来说可能耗时一分钟。之后，应用程序在运行时被解密并执行。 -一旦在发布模式下启用 flash 加密，引导加载程序将写保护 ``{IDF_TARGET_CRYPT_CNT}`` eFuse。 +一旦在量产模式下启用 flash 加密，引导加载程序将写保护 ``{IDF_TARGET_CRYPT_CNT}`` eFuse。 请使用 :ref:`OTA 方案 ` 对字段中的明文进行后续更新。 @@ -571,7 +571,7 @@ flash 加密设置 - 不要在多个设备之间重复使用同一个 flash 加密密钥，这样攻击者就无法从一台设备上复制加密数据后再将其转移到第二台设备上。 :esp32: - 在使用 ESP32 V3 时，如果生产设备不需要 UART ROM 下载模式，那么则该禁用该模式以增加设备安全性。这可以通过在应用程序启动时调用 :cpp:func:`esp_efuse_disable_rom_download_mode` 来实现。或者，可将项目 :ref:`CONFIG_ESP32_REV_MIN` 级别配置为 3（仅针对 ESP32 V3），然后选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久性的禁用 ROM 下载模式（推荐）”。在早期的 ESP32 版本上无法禁用 ROM 下载模式。 - :not esp32: - 如果不需要 UART ROM 下载模式，则应完全禁用该模式，或者永久设置为“安全下载模式”。安全下载模式永久性地将可用的命令限制在更新 SPI 配置、更改波特率、基本的 flash 写入和使用 `get_security_info` 命令返回当前启用的安全功能摘要。默认在发布模式下第一次启动时设置为安全下载模式。要完全禁用下载模式，请选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久禁用 ROM 下载模式（推荐）”或在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。 + :not esp32: - 如果不需要 UART ROM 下载模式，则应完全禁用该模式，或者永久设置为“安全下载模式”。安全下载模式永久性地将可用的命令限制在更新 SPI 配置、更改波特率、基本的 flash 写入和使用 `get_security_info` 命令返回当前启用的安全功能摘要。默认在量产模式下第一次启动时设置为安全下载模式。要完全禁用下载模式，请选择 :ref:`CONFIG_SECURE_UART_ROM_DL_MODE` 为“永久禁用 ROM 下载模式（推荐）”或在运行时调用 :cpp:func:`esp_efuse_disable_rom_download_mode`。 - 启用 :doc:`安全启动` 作为额外的保护层，防止攻击者在启动前有选择地破坏 flash 中某部分。 外部启用 flash 加密 @@ -789,7 +789,7 @@ OTA 更新 在开发模式下，推荐的方法是 :ref:`encrypt-partitions`。 -在发布模式下，如果主机上有存储在 eFuse 中的相同密钥的副本，那么就可以在主机上对文件进行预加密，然后进行烧录，具体请参考 :ref:`manual-encryption`。 +在量产模式下，如果主机上有存储在 eFuse 中的相同密钥的副本，那么就可以在主机上对文件进行预加密，然后进行烧录，具体请参考 :ref:`manual-encryption`。 关闭 flash 加密 ----------------- @@ -876,6 +876,10 @@ flash 加密与安全启动 - 如果未重新烧录引导加载程序，则仍然可以 :ref:`使用预生成的 flash 加密密钥重新烧录 `。重新烧录引导加载程序时，需在安全启动配置中启用相同的 :ref:`可重新烧录 ` 选项。 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND and SOC_ECDSA_SUPPORT_CURVE_P384 + + - 在启用 flash 加密量产模式时，建议在首次启动时就设置 :ref:`xts-aes-pseudo-round-func` 所需的强度。如果你的工作流程需要在首次启动后更新该函数的强度，则应启用 :ref:`CONFIG_SECURE_BOOT_SKIP_WRITE_PROTECTION_SCA`，避免在启动过程中对该位进行写保护。 + .. _flash-encryption-without-secure-boot: flash 加密的高级功能 @@ -986,7 +990,7 @@ flash 加密的高级功能 JTAG 调试 ^^^^^^^^^^^^^^ -默认情况下，当启用 flash 加密（开发或发布模式）时，将通过 eFuse 禁用 JTAG 调试。引导加载程序在首次启动时执行此操作，同时启用 flash 加密。 +默认情况下，当启用 flash 加密（开发或量产模式）时，将通过 eFuse 禁用 JTAG 调试。引导加载程序在首次启动时执行此操作，同时启用 flash 加密。 请参考 :ref:`jtag-debugging-security-features` 了解更多关于使用 JTAG 调试与 flash 加密的信息。 diff --git a/docs/zh_CN/security/security-features-enablement-workflows.rst b/docs/zh_CN/security/security-features-enablement-workflows.rst index 8002573ea3..d8e5e7dc01 100644 --- a/docs/zh_CN/security/security-features-enablement-workflows.rst +++ b/docs/zh_CN/security/security-features-enablement-workflows.rst @@ -250,7 +250,7 @@ :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``：永久禁用 JTAG :not esp32: - ``DIS_DOWNLOAD_MANUAL_ENCRYPT``：禁用 UART 引导加载程序加密访问 :SOC_EFUSE_DIS_DOWNLOAD_MSPI: - ``DIS_DOWNLOAD_MSPI``：禁用下载模式下的 MSPI 访问 - :SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - ``XTS_DPA_PSEUDO_LEVEL``：启用 XTS-AES 外设的伪轮次功能。要烧录到 eFuse 中的值可以是 1、2 或 3，表示安全等级。默认情况下，ESP-IDF 的引导加载程序在启动过程中启用 flash 加密的发布模式时，会将该 eFuse 的值配置为 1。 + :SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - ``XTS_DPA_PSEUDO_LEVEL``：启用 XTS-AES 外设的伪轮次功能。要烧录到 eFuse 中的值可以是 1、2 或 3，表示安全等级。默认情况下，ESP-IDF 的引导加载程序在启动过程中启用 flash 加密的量产模式时，会将该 eFuse 的值配置为 1。 可运行以下命令烧录相应的 eFuse： @@ -292,16 +292,16 @@ 6. 配置项目 - 项目的引导加载程序和应用程序二进制文件必须使用默认配置的 flash 加密发布模式进行构建。 + 项目的引导加载程序和应用程序二进制文件必须使用默认配置的 flash 加密量产模式进行构建。 - 如下所示，可以在 menuconfig 中设置 flash 加密发布模式： + 如下所示，可以在 menuconfig 中设置 flash 加密量产模式： .. list:: - :ref:`启动时启用 flash 加密 `。 - :esp32: - :ref:`选择发布模式 ` （注意，若选择发布模式，则将烧录 ``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位，ROM 下载模式下 flash 加密硬件将被禁用）。 + :esp32: - :ref:`选择量产模式 ` （注意，若选择量产模式，则将烧录 ``DISABLE_DL_ENCRYPT`` 和 ``DISABLE_DL_DECRYPT`` eFuse 位，ROM 下载模式下 flash 加密硬件将被禁用）。 :esp32: - :ref:`选择 UART ROM 下载模式（永久禁用（推荐））` （注意，此选项仅在 :ref:`CONFIG_ESP32_REV_MIN` 设为 3 (ESP32 V3) 时可用）。UART ROM 下载模式在默认设置中自动启用，但建议永久禁用此模式以减少攻击者可用的选项。 - :not esp32: - :ref:`选择发布模式 ` （注意，若选择发布模式，则将烧录 ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位，ROM 下载模式下 flash 加密硬件将被禁用）。 + :not esp32: - :ref:`选择量产模式 ` （注意，若选择量产模式，则将烧录 ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse 位，ROM 下载模式下 flash 加密硬件将被禁用）。 :not esp32: - :ref:`选择 UART ROM 下载模式（永久切换到安全模式（推荐））`。这是推荐的默认选项，如果不需要，也可将其更改为永久禁用 UART ROM 下载模式。 - :ref:`选择适当的引导加载程序日志级别 `。 - 保存配置并退出。 @@ -500,8 +500,8 @@ flash 加密指南 :SOC_EFUSE_DIS_USB_JTAG: - ``DIS_USB_JTAG``：禁止从 USB 切换到 JTAG。 :SOC_EFUSE_DIS_PAD_JTAG: - ``DIS_PAD_JTAG``：永久禁用 JTAG。 :SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS: - ``SECURE_BOOT_AGGRESSIVE_REVOKE``：主动吊销密钥摘要。详请请参阅 :ref:`secure-boot-v2-aggressive-key-revocation`。 - :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``：禁止写入 ECDSA 曲线模式。 - :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``：禁止写入 SHA-384 Secure Boot 的 SHA-384 eFuse 位。 + :SOC_ECDSA_P192_CURVE_DEFAULT_DISABLED: - ``WR_DIS_ECDSA_CURVE_MODE``：禁止写入 ECDSA 曲线模式的 eFuse 位。由于此写保护位与 ``ECC_FORCE_CONST_TIME`` 共享，建议先配置好 ``ECC_FORCE_CONST_TIME`` eFuse 字段后，再设置此写保护位）。 + :SOC_ECDSA_SUPPORT_CURVE_P384: - ``WR_DIS_SECURE_BOOT_SHA384_EN``：禁止写入 SHA-384 Secure Boot 的 eFuse 位。由于此写保护位与 ``XTS_DPA_PSEUDO_LEVEL`` 和 ``ECC_FORCE_CONST_TIME`` 共享，建议先配置好这两个 eFuse，再设置此写保护位。 运行以下命令烧录相应的 eFuse： diff --git a/docs/zh_CN/security/security.rst b/docs/zh_CN/security/security.rst index 496148ee1f..0eb4c6600b 100644 --- a/docs/zh_CN/security/security.rst +++ b/docs/zh_CN/security/security.rst @@ -75,7 +75,7 @@ flash 加密功能可以加密外部 flash 中的内容，从而保护存储在 flash 加密最佳实践 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -* 建议在生产环境中使用 flash 加密的发布模式。 +* 建议在生产环境中使用 flash 加密的量产模式。 * 建议为每个设备生成唯一的 flash 加密密钥。 * 启用 :ref:`secure_boot-guide` 作为额外保护层，防止 flash 在启动前遭受恶意攻击。