blackbeard420/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf synced 2025-03-09 09:09:10 -04:00
Code Issues Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
harshal.patil 2025-01-17 10:56:59 +05:30
parent a29dadbabc
commit b285e2789f
No known key found for this signature in database
GPG Key ID: 67334E837530B75C
12 changed files with 145 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
components/bootloader/Kconfig.projbuild
View File

@ -1073,6 +1073,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

13
components/bootloader_support/src/esp32h2/flash_encryption_secure_features.c
View File

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

23
components/bootloader_support/src/flash_encrypt.c
View File

@ -1,5 +1,5 @@
/*
* SPDX-FileCopyrightText: 2015-2021 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
@ -201,6 +204,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
@ -438,6 +448,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

19
components/hal/esp32/include/hal/spi_flash_encrypted_ll.h
View File

@ -1,16 +1,8 @@
// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*******************************************************************************
* NOTICE
@ -19,6 +11,7 @@
******************************************************************************/
// The Lowlevel layer for SPI Flash Encryption.
#pragma once
#include "soc/dport_reg.h"
#include "soc/flash_encryption_reg.h"

7
components/hal/esp32c2/include/hal/spi_flash_encrypted_ll.h
View File

@ -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>
@ -23,7 +24,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.
@ -50,7 +51,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
*

23
components/hal/esp32c3/include/hal/spi_flash_encrypted_ll.h
View File

@ -1,16 +1,8 @@
// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*******************************************************************************
* NOTICE
@ -19,6 +11,7 @@
******************************************************************************/
// The Lowlevel layer for SPI Flash Encryption.
#pragma once
#include <stdbool.h>
#include <string.h>
@ -31,7 +24,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.
@ -58,7 +51,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
*

7
components/hal/esp32c6/include/hal/spi_flash_encrypted_ll.h
View File

@ -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>
@ -23,7 +24,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.
@ -50,7 +51,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
*

1
components/hal/esp32h2/include/hal/spi_flash_encrypted_ll.h
View File

@ -11,6 +11,7 @@
******************************************************************************/
// The Lowlevel layer for SPI Flash Encryption.
#pragma once
#include <stdbool.h>
#include <string.h>

23
components/hal/esp32s2/include/hal/spi_flash_encrypted_ll.h
View File

@ -1,16 +1,8 @@
// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*******************************************************************************
* NOTICE
@ -19,6 +11,7 @@
******************************************************************************/
// The Lowlevel layer for SPI Flash Encryption.
#pragma once
#include <stdbool.h>
#include <string.h>
@ -31,7 +24,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.
@ -68,7 +61,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
*

23
components/hal/esp32s3/include/hal/spi_flash_encrypted_ll.h
View File

@ -1,16 +1,8 @@
// Copyright 2015-2021 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*******************************************************************************
* NOTICE
@ -19,6 +11,7 @@
******************************************************************************/
// The Lowlevel layer for SPI Flash Encryption.
#pragma once
#include <stdbool.h>
#include <string.h>
@ -31,7 +24,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.
@ -58,7 +51,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
*

34
docs/en/security/flash-encryption.rst
View File

@ -522,6 +522,7 @@ To use this mode, take the following steps:
:esp32: - :ref:`Select UART ROM download mode (Permanently disabled (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>` (Note that this option is only available when :ref:`CONFIG_ESP32_REV_MIN` is set to 3 (ESP32 V3).) The default choice is to keep UART ROM download mode enabled, however it's recommended to permanently disable this mode to reduce the options available to an attacker.
:not esp32: - :ref:`Select Release mode <CONFIG_SECURE_FLASH_ENCRYPTION_MODE>` (Note that once Release mode is selected, the ``EFUSE_DIS_DOWNLOAD_MANUAL_ENCRYPT`` eFuse bit will be burned to disable flash encryption hardware in ROM Download Mode.)
:not esp32: - :ref:`Select UART ROM download mode (Permanently switch to Secure mode (recommended)) <CONFIG_SECURE_UART_ROM_DL_MODE>`. This is the default option, and is recommended. It is also possible to change this configuration setting to permanently disable UART ROM download mode, if this mode is not needed.
:SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND: - :ref:`Select enable XTS-AES's pseudo rounds function <CONFIG_SECURE_FLASH_PSEUDO_ROUND_FUNC>`. This option is selected by default and its strength is configured to level low considering the performance impact on the flash encryption/decryption operations. Please refer to :ref:`xts-aes-pseudo-round-func` for more information regarding the performance impact per security level.
- :ref:`Select the appropriate bootloader log verbosity <CONFIG_BOOTLOADER_LOG_LEVEL>`
- Save the configuration and exit.
@ -1102,3 +1103,36 @@ The following sections provide some reference information about the operation of
- The flash encryption key is stored in ``BLOCK_KEY0`` eFuse and, by default, is protected from further writes or software readout.
- To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code.
.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_SUPPORT_PSEUDO_ROUND
Protection Against Side-Channel Attacks
---------------------------------------
.. _xts-aes-pseudo-round-func:
Pseudo-Round Function
^^^^^^^^^^^^^^^^^^^^^
{IDF_TARGET_NAME} incorporates a pseudo-round function in the XTS-AES peripheral, thus enabling the peripheral to randomly insert pseudo-rounds before and after the original operation rounds and also generate a pseudo key to perform these dummy operations.
These operations do not alter the original result, but they increase the complexity to perform side channel analysis attacks by randomizing the power profile.
:ref:`CONFIG_SECURE_FLASH_PSEUDO_ROUND_FUNC_STRENGTH` can be used to select the strength of the pseudo-round function. Increasing the strength improves the security provided, but would slow down the XTS-AES operations.
.. list-table:: Performance impact on XTS-AES operations per strength level
:widths: 10 10
:header-rows: 1
:align: center
* - **Strength**
- **Performance Impact**
* - Low
- < 0.5 %
* - Medium
- 6.2 %
* - High
- 18 %
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.
Considering the above performance impact, ESP-IDF by-default enables low strength configuration for the pseudo-round function for minimal performance impact.

4
tools/ci/check_copyright_ignore.txt
View File

@ -590,7 +590,6 @@ components/freertos/FreeRTOS-Kernel-SMP/timers.c
components/hal/ds_hal.c
components/hal/esp32/include/hal/aes_ll.h
components/hal/esp32/include/hal/mpu_ll.h
components/hal/esp32/include/hal/spi_flash_encrypted_ll.h
components/hal/esp32/include/hal/touch_sensor_hal.h
components/hal/esp32/include/hal/trace_ll.h
components/hal/esp32c3/hmac_hal.c
@ -599,19 +598,16 @@ components/hal/esp32c3/include/hal/hmac_hal.h
components/hal/esp32c3/include/hal/hmac_ll.h
components/hal/esp32c3/include/hal/mpu_ll.h
components/hal/esp32c3/include/hal/sha_ll.h
components/hal/esp32c3/include/hal/spi_flash_encrypted_ll.h
components/hal/esp32c3/include/hal/uhci_ll.h
components/hal/esp32c3/rtc_cntl_hal.c
components/hal/esp32s2/include/hal/crypto_dma_ll.h
components/hal/esp32s2/include/hal/dedic_gpio_ll.h
components/hal/esp32s2/include/hal/mpu_ll.h
components/hal/esp32s2/include/hal/sha_ll.h
components/hal/esp32s2/include/hal/spi_flash_encrypted_ll.h
components/hal/esp32s2/include/hal/trace_ll.h
components/hal/esp32s2/include/hal/usb_ll.h
components/hal/esp32s3/include/hal/mpu_ll.h
components/hal/esp32s3/include/hal/sha_ll.h
components/hal/esp32s3/include/hal/spi_flash_encrypted_ll.h
components/hal/esp32s3/include/hal/uhci_ll.h
components/hal/esp32s3/include/hal/usb_ll.h
components/hal/include/hal/aes_types.h