feat(bootloader_support): Permanently enable XTS-AES pseudo rounds when FE release mode is enabled

Harshal5 · Harshal5 · commit b06a4c198a57 · 2025-01-21T12:28:23.000+05:30
diff --git a/components/bootloader/Kconfig.projbuild b/components/bootloader/Kconfig.projbuild
@@ -1134,6 +1134,44 @@ menu "Security features"
 
             If not set, the app does not care if the flash encryption eFuse bit is set or not.
 
+    config SECURE_FLASH_PSEUDO_ROUND_FUNC
+        bool "Permanently enable XTS-AES's pseudo rounds function"
+        default y
+        depends on SECURE_FLASH_ENCRYPTION_MODE_RELEASE && SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND
+        help
+            If set (default), the bootloader will permanently enable the XTS-AES peripheral's pseudo rounds function.
+            Note: Enabling this config would burn an efuse.
+
+    choice SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH
+        prompt "Strength of the pseudo rounds function"
+        depends on SECURE_FLASH_PSEUDO_ROUND_FUNC
+        default SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_LOW
+        help
+            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.
+            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.
+            For more info regarding the performance impact, please checkout the pseudo round function section of the
+            security guide documentation.
+
+        config SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_LOW
+            bool "Low"
+
+        config SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_MEDIUM
+            bool "Medium"
+
+        config SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_HIGH
+            bool "High"
+    endchoice
+
+    config SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH
+        int
+        default 1 if SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_LOW
+        default 2 if SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_MEDIUM
+        default 3 if SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH_HIGH
+
     config SECURE_ROM_DL_MODE_ENABLED
         bool
         default y if SOC_SUPPORTS_SECURE_DL_MODE && !SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT
diff --git a/components/bootloader_support/src/esp32h2/flash_encryption_secure_features.c b/components/bootloader_support/src/esp32h2/flash_encryption_secure_features.c
@@ -1,15 +1,18 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include <stdint.h>
 #include <strings.h>
 #include "esp_flash_encrypt.h"
 #include "esp_secure_boot.h"
 #include "esp_efuse.h"
 #include "esp_efuse_table.h"
 #include "esp_log.h"
+#include "hal/spi_flash_encrypted_ll.h"
+#include "soc/soc_caps.h"
 #include "sdkconfig.h"
 
 static __attribute__((unused)) const char *TAG = "flash_encrypt";
@@ -33,6 +36,14 @@ esp_err_t esp_flash_encryption_enable_secure_features(void)
 
     esp_efuse_write_field_bit(ESP_EFUSE_DIS_DIRECT_BOOT);
 
+#if defined(CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE) && defined(SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND)
+    if (spi_flash_encrypt_ll_is_pseudo_rounds_function_supported()) {
+        ESP_LOGI(TAG, "Enable XTS-AES pseudo rounds function...");
+        uint8_t xts_pseudo_level = CONFIG_SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH;
+        esp_efuse_write_field_blob(ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL, &xts_pseudo_level, ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL[0]->bit_count);
+    }
+#endif
+
 #if defined(CONFIG_SECURE_BOOT_V2_ENABLED) && !defined(CONFIG_SECURE_BOOT_V2_ALLOW_EFUSE_RD_DIS)
     // This bit is set when enabling Secure Boot V2, but we can't enable it until this later point in the first boot
     // otherwise the Flash Encryption key cannot be read protected
diff --git a/components/bootloader_support/src/flash_encrypt.c b/components/bootloader_support/src/flash_encrypt.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -12,6 +12,9 @@
 #include "esp_flash_encrypt.h"
 #include "esp_secure_boot.h"
 #include "hal/efuse_hal.h"
+#include "hal/spi_flash_encrypted_ll.h"
+#include "hal/spi_flash_encrypt_hal.h"
+#include "soc/soc_caps.h"
 
 #if CONFIG_IDF_TARGET_ESP32
 #define CRYPT_CNT ESP_EFUSE_FLASH_CRYPT_CNT
@@ -207,6 +210,13 @@ void esp_flash_encryption_set_release_mode(void)
 #endif // CONFIG_SOC_FLASH_ENCRYPTION_XTS_AES_128_DERIVED
 #endif // !CONFIG_IDF_TARGET_ESP32
 
+#ifdef SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND
+    if (spi_flash_encrypt_ll_is_pseudo_rounds_function_supported()) {
+        uint8_t xts_pseudo_level = ESP_XTS_AES_PSEUDO_ROUNDS_LOW;
+        esp_efuse_write_field_blob(ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL, &xts_pseudo_level, ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL[0]->bit_count);
+    }
+#endif
+
 #ifdef CONFIG_IDF_TARGET_ESP32
     esp_efuse_write_field_bit(ESP_EFUSE_WR_DIS_DIS_CACHE);
 #else
@@ -468,6 +478,17 @@ bool esp_flash_encryption_cfg_verify_release_mode(void)
     }
     result &= secure;
 
+#if SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND
+    if (spi_flash_encrypt_ll_is_pseudo_rounds_function_supported()) {
+        uint8_t xts_pseudo_level = 0;
+        esp_efuse_read_field_blob(ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL, &xts_pseudo_level, ESP_EFUSE_XTS_DPA_PSEUDO_LEVEL[0]->bit_count);
+        if (!xts_pseudo_level) {
+            result &= false;
+            ESP_LOGW(TAG, "Not enabled XTS-AES pseudo rounds function (set XTS_DPA_PSEUDO_LEVEL->1 or more)");
+        }
+    }
+#endif
+
     return result;
 }
 #endif // not CONFIG_IDF_TARGET_ESP32
diff --git a/components/hal/esp32/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32/include/hal/spi_flash_encrypted_ll.h
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include "soc/dport_reg.h"
 #include "soc/flash_encryption_reg.h"
diff --git a/components/hal/esp32c2/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32c2/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/components/hal/esp32c3/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32c3/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/components/hal/esp32c5/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32c5/include/hal/spi_flash_encrypted_ll.h
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
diff --git a/components/hal/esp32c6/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32c6/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/components/hal/esp32c61/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32c61/include/hal/spi_flash_encrypted_ll.h
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
diff --git a/components/hal/esp32h2/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32h2/include/hal/spi_flash_encrypted_ll.h
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
diff --git a/components/hal/esp32p4/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32p4/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/components/hal/esp32s2/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32s2/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -61,7 +62,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/components/hal/esp32s3/include/hal/spi_flash_encrypted_ll.h b/components/hal/esp32s3/include/hal/spi_flash_encrypted_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,6 +11,7 @@
  ******************************************************************************/
 
 // The Lowlevel layer for SPI Flash Encryption.
+#pragma once
 
 #include <stdbool.h>
 #include <string.h>
@@ -24,7 +25,7 @@
 extern "C" {
 #endif
 
-/// Choose type of chip you want to encrypt manully
+/// Choose type of chip you want to encrypt manually
 typedef enum
 {
     FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.
@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)
 }
 
 /**
- * Choose type of chip you want to encrypt manully
+ * Choose type of chip you want to encrypt manually
  *
  * @param type The type of chip to be encrypted
  *
diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst
diff --git a/docs/en/security/security-features-enablement-workflows.rst b/docs/en/security/security-features-enablement-workflows.rst

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD`
	`2`	`+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD`
`3`	`3`	`*`
`4`	`4`	`* SPDX-License-Identifier: Apache-2.0`
`5`	`5`	`*/`
`@@ -11,6 +11,7 @@`
`11`	`11`	`******************************************************************************/`
`12`	`12`
`13`	`13`	`// The Lowlevel layer for SPI Flash Encryption.`
	`14`	`+#pragma once`
`14`	`15`
`15`	`16`	`#include <stdbool.h>`
`16`	`17`	`#include <string.h>`
`@@ -24,7 +25,7 @@`
`24`	`25`	`extern "C" {`
`25`	`26`	`#endif`
`26`	`27`
`27`		`-/// Choose type of chip you want to encrypt manully`
	`28`	`+/// Choose type of chip you want to encrypt manually`
`28`	`29`	`typedef enum`
`29`	`30`	`{`
`30`	`31`	`FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.`
`@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)`
`51`	`52`	`}`
`52`	`53`
`53`	`54`	`/**`
`54`		`- * Choose type of chip you want to encrypt manully`
	`55`	`+ * Choose type of chip you want to encrypt manually`
`55`	`56`	`*`
`56`	`57`	`* @param type The type of chip to be encrypted`
`57`	`58`	`*`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD`
	`2`	`+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD`
`3`	`3`	`*`
`4`	`4`	`* SPDX-License-Identifier: Apache-2.0`
`5`	`5`	`*/`
`@@ -11,6 +11,7 @@`
`11`	`11`	`******************************************************************************/`
`12`	`12`
`13`	`13`	`// The Lowlevel layer for SPI Flash Encryption.`
	`14`	`+#pragma once`
`14`	`15`
`15`	`16`	`#include <stdbool.h>`
`16`	`17`	`#include <string.h>`
`@@ -24,7 +25,7 @@`
`24`	`25`	`extern "C" {`
`25`	`26`	`#endif`
`26`	`27`
`27`		`-/// Choose type of chip you want to encrypt manully`
	`28`	`+/// Choose type of chip you want to encrypt manually`
`28`	`29`	`typedef enum`
`29`	`30`	`{`
`30`	`31`	`FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.`
`@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)`
`51`	`52`	`}`
`52`	`53`
`53`	`54`	`/**`
`54`		`- * Choose type of chip you want to encrypt manully`
	`55`	`+ * Choose type of chip you want to encrypt manually`
`55`	`56`	`*`
`56`	`57`	`* @param type The type of chip to be encrypted`
`57`	`58`	`*`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/*`
`2`		`- * SPDX-FileCopyrightText: 2022-2023 Espressif Systems (Shanghai) CO LTD`
	`2`	`+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD`
`3`	`3`	`*`
`4`	`4`	`* SPDX-License-Identifier: Apache-2.0`
`5`	`5`	`*/`
`@@ -11,6 +11,7 @@`
`11`	`11`	`******************************************************************************/`
`12`	`12`
`13`	`13`	`// The Lowlevel layer for SPI Flash Encryption.`
	`14`	`+#pragma once`
`14`	`15`
`15`	`16`	`#include <stdbool.h>`
`16`	`17`	`#include <string.h>`
`@@ -24,7 +25,7 @@`
`24`	`25`	`extern "C" {`
`25`	`26`	`#endif`
`26`	`27`
`27`		`-/// Choose type of chip you want to encrypt manully`
	`28`	`+/// Choose type of chip you want to encrypt manually`
`28`	`29`	`typedef enum`
`29`	`30`	`{`
`30`	`31`	`FLASH_ENCRYPTION_MANU = 0, ///!< Manually encrypt the flash chip.`
`@@ -51,7 +52,7 @@ static inline void spi_flash_encrypt_ll_disable(void)`
`51`	`52`	`}`
`52`	`53`
`53`	`54`	`/**`
`54`		`- * Choose type of chip you want to encrypt manully`
	`55`	`+ * Choose type of chip you want to encrypt manually`
`55`	`56`	`*`
`56`	`57`	`* @param type The type of chip to be encrypted`
`57`	`58`	`*`