Merge branch 'feature/anti_dpa_configuration_c6_h2' into 'master'

esp32c6/esp32h2: crypto: add support for DPA protection configuration

Closes IDF-6973

See merge request espressif/esp-idf!23921

components/esp_hw_support/CMakeLists.txt

@@ -82,6 +82,10 @@ if(NOT BOOTLOADER_BUILD)
         list(APPEND srcs "esp_etm.c")
     endif()
 
+    if(CONFIG_SOC_CRYPTO_DPA_PROTECTION_SUPPORTED)
+        list(APPEND srcs "esp_dpa_protection.c")
+    endif()
+
     if(CONFIG_SOC_DIG_SIGN_SUPPORTED)
         list(APPEND srcs "esp_ds.c")
     endif()
@@ -141,6 +145,9 @@ if(NOT BOOTLOADER_BUILD)
     if(CONFIG_SPIRAM)
         idf_component_optional_requires(PRIVATE esp_psram)
     endif()
+    if(CONFIG_SOC_CRYPTO_DPA_PROTECTION_SUPPORTED)
+        target_link_libraries(${COMPONENT_LIB} PRIVATE "-u esp_crypto_dpa_prot_include_impl")
+    endif()
 endif()
 
 target_compile_options(${COMPONENT_LIB} PRIVATE "-Wno-format")

components/esp_hw_support/Kconfig

@@ -237,4 +237,42 @@ menu "Hardware Settings"
             default 40 if XTAL_FREQ_40
             default 0  if XTAL_FREQ_AUTO
     endmenu
+
+    menu "Crypto DPA Protection"
+        depends on SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
+        config ESP_CRYPTO_DPA_PROTECTION_AT_STARTUP
+            bool "Enable crypto DPA protection at startup"
+            default y
+            help
+                This config controls the DPA (Differential Power Analysis) protection
+                knob for the crypto peripherals. DPA protection dynamically adjusts the
+                clock frequency of the crypto peripheral. DPA protection helps to make it
+                difficult to perform SCA attacks on the crypto peripherals. However,
+                there is also associated performance impact based on the security level
+                set. Please refer to the TRM for more details.
+
+        choice ESP_CRYPTO_DPA_PROTECTION_LEVEL
+            prompt "DPA protection level"
+            depends on ESP_CRYPTO_DPA_PROTECTION_AT_STARTUP
+            default ESP_CRYPTO_DPA_PROTECTION_LEVEL_LOW
+            help
+                Configure the DPA protection security level
+
+            config ESP_CRYPTO_DPA_PROTECTION_LEVEL_LOW
+                bool "Security level low"
+
+            config ESP_CRYPTO_DPA_PROTECTION_LEVEL_MEDIUM
+                bool "Security level medium"
+
+            config ESP_CRYPTO_DPA_PROTECTION_LEVEL_HIGH
+                bool "Security level high"
+        endchoice
+
+        config ESP_CRYPTO_DPA_PROTECTION_LEVEL
+            int
+            default 1 if ESP_CRYPTO_DPA_PROTECTION_LEVEL_LOW
+            default 2 if ESP_CRYPTO_DPA_PROTECTION_LEVEL_MEDIUM
+            default 3 if ESP_CRYPTO_DPA_PROTECTION_LEVEL_HIGH
+
+    endmenu
 endmenu

components/esp_hw_support/esp_dpa_protection.c

@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <string.h>
+#include "sdkconfig.h"
+#include "soc/hp_system_reg.h"
+#include "esp_dpa_protection.h"
+
+static inline void esp_crypto_dpa_set_level(esp_crypto_dpa_sec_level_t level)
+{
+    assert(level >= ESP_CRYPTO_DPA_SEC_LEVEL_LOW && level <= ESP_CRYPTO_DPA_SEC_LEVEL_HIGH);
+    REG_SET_BIT(HP_SYSTEM_SEC_DPA_CONF_REG, HP_SYSTEM_SEC_DPA_CFG_SEL);
+    REG_SET_FIELD(HP_SYSTEM_SEC_DPA_CONF_REG, HP_SYSTEM_SEC_DPA_LEVEL, level);
+}
+
+#if CONFIG_ESP_CRYPTO_DPA_PROTECTION_AT_STARTUP
+static void __attribute__((constructor)) esp_crypto_dpa_protection_startup(void)
+{
+    esp_crypto_dpa_set_level(CONFIG_ESP_CRYPTO_DPA_PROTECTION_LEVEL);
+}
+#endif
+
+void esp_crypto_dpa_protection_enable(esp_crypto_dpa_sec_level_t level)
+{
+    esp_crypto_dpa_set_level(level);
+}
+
+void esp_crypto_dpa_protection_disable(void)
+{
+    REG_CLR_BIT(HP_SYSTEM_SEC_DPA_CONF_REG, HP_SYSTEM_SEC_DPA_CFG_SEL);
+}
+
+void esp_crypto_dpa_prot_include_impl(void)
+{
+    // Linker hook, exists for no other purpose
+}

components/esp_hw_support/include/esp_dpa_protection.h

@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    ESP_CRYPTO_DPA_SEC_LEVEL_OFF = 0,      /*!< DPA protection disabled */
+    ESP_CRYPTO_DPA_SEC_LEVEL_LOW,          /*!< DPA protection level low */
+    ESP_CRYPTO_DPA_SEC_LEVEL_MIDDLE,       /*!< DPA protection level medium */
+    ESP_CRYPTO_DPA_SEC_LEVEL_HIGH,         /*!< DPA protection level high */
+} esp_crypto_dpa_sec_level_t;
+
+/**
+ * @brief Enable DPA (Differential Power Analysis) related protection
+ *
+ * @note
+ * Enabling the DPA protection can help to make it difficult to perform SCA
+ * attacks on the crypto peripherals. However, based on the security level
+ * set there will be a performance impact, higher the level higher the impact.
+ * Please refer to the TRM for more details.
+ *
+ * @param level DPA Security Level of type `esp_crypto_dpa_sec_level_t`
+ */
+void esp_crypto_dpa_protection_enable(esp_crypto_dpa_sec_level_t level);
+
+/**
+ * @brief Disable DPA (Differential Power Analysis) related protection
+ */
+void esp_crypto_dpa_protection_disable(void);
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c6/include/soc/Kconfig.soc_caps.in

@@ -1055,6 +1055,10 @@ config SOC_FLASH_ENCRYPTION_XTS_AES_128
     bool
     default y
 
+config SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
+    bool
+    default y
+
 config SOC_UART_NUM
     int
     default 2

components/soc/esp32c6/include/soc/soc_caps.h

@@ -433,6 +433,9 @@
 #define SOC_FLASH_ENCRYPTION_XTS_AES        1
 #define SOC_FLASH_ENCRYPTION_XTS_AES_128    1
 
+/*------------------------ Anti DPA (Security) CAPS --------------------------*/
+#define SOC_CRYPTO_DPA_PROTECTION_SUPPORTED     1
+
 /*-------------------------- UART CAPS ---------------------------------------*/
 // ESP32-C6 has 2 UARTs
 #define SOC_UART_NUM                    (2)

components/soc/esp32h2/include/soc/Kconfig.soc_caps.in

@@ -1023,6 +1023,10 @@ config SOC_FLASH_ENCRYPTION_XTS_AES_128
     bool
     default y
 
+config SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
+    bool
+    default y
+
 config SOC_UART_NUM
     int
     default 2

components/soc/esp32h2/include/soc/soc_caps.h

@@ -429,6 +429,9 @@
 #define SOC_FLASH_ENCRYPTION_XTS_AES        1
 #define SOC_FLASH_ENCRYPTION_XTS_AES_128    1
 
+/*------------------------ Anti DPA (Security) CAPS --------------------------*/
+#define SOC_CRYPTO_DPA_PROTECTION_SUPPORTED     1
+
 /*-------------------------- UART CAPS ---------------------------------------*/
 // ESP32-H2 has 2 UARTs
 #define SOC_UART_NUM                (2)

docs/en/security/security.rst

@@ -86,6 +86,16 @@ Flash Encryption Best Practices
 
     .. note:: This feature can help to prevent the possibility of remote code injection due to the existing vulnerabilities in the software.
 
+.. only:: SOC_CRYPTO_DPA_PROTECTION_SUPPORTED
+
+    DPA (Differential Power Analysis) Protection
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    {IDF_TARGET_NAME} has support for protection mechanisms against the Differential Power Analysis related security attacks. DPA protection dynamically adjusts the clock frequency of the crypto peripherals, thereby blurring the power consumption trajectory during its operation. Based on the configured DPA security level, the clock variation range changes. Please refer to the TRM for more details on this topic.
+    :ref:`CONFIG_ESP_CRYPTO_DPA_PROTECTION_LEVEL` can help to select the DPA level. Higher level means better security, but it can also have an associated performance impact. By default, the lowest DPA level is kept enabled but it can be modified based on the security requirement.
+
+    .. note:: Please note that hardware :doc:`RNG <../api-reference/system/random>` must be enabled for DPA protection to work correctly.
+
 Debug Interfaces
 ~~~~~~~~~~~~~~~~