diff --git a/components/efuse/src/esp_efuse_api_key_esp32xx.c b/components/efuse/src/esp_efuse_api_key_esp32xx.c index 2b3a085acd..eb745ad769 100644 --- a/components/efuse/src/esp_efuse_api_key_esp32xx.c +++ b/components/efuse/src/esp_efuse_api_key_esp32xx.c @@ -302,7 +302,7 @@ esp_err_t esp_efuse_write_key(esp_efuse_block_t block, esp_efuse_purpose_t purpo ESP_EFUSE_CHK(esp_efuse_write_field_blob(s_table[idx].key, key, key_size_bytes * 8)); ESP_EFUSE_CHK(esp_efuse_set_key_dis_write(block)); if (purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_128_KEY || -#ifdef SOC_EFUSE_SUPPORT_XTS_AES_256_KEYS +#ifdef SOC_FLASH_ENCRYPTION_XTS_AES_256 purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1 || purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2 || #endif diff --git a/components/efuse/test/test_efuse_keys.c b/components/efuse/test/test_efuse_keys.c index cbc74d71d4..24f3190bed 100644 --- a/components/efuse/test/test_efuse_keys.c +++ b/components/efuse/test/test_efuse_keys.c @@ -62,7 +62,7 @@ static esp_err_t s_check_key(esp_efuse_block_t num_key, void* wr_key) TEST_ASSERT_TRUE(esp_efuse_get_key_dis_write(num_key)); if (purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_128_KEY || -#ifdef SOC_EFUSE_SUPPORT_XTS_AES_256_KEYS +#ifdef SOC_FLASH_ENCRYPTION_XTS_AES_256 purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1 || purpose == ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2 || #endif @@ -149,7 +149,7 @@ TEST_CASE("Test 1 esp_efuse_write_key for FPGA", "[efuse]") esp_efuse_purpose_t purpose [] = { ESP_EFUSE_KEY_PURPOSE_USER, ESP_EFUSE_KEY_PURPOSE_RESERVED, -#ifdef SOC_EFUSE_SUPPORT_XTS_AES_256_KEYS +#ifdef SOC_FLASH_ENCRYPTION_XTS_AES_256 ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1, ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2, #else @@ -217,7 +217,7 @@ TEST_CASE("Test esp_efuse_write_keys", "[efuse]") esp_efuse_block_t key_block = EFUSE_BLK_MAX; enum { BLOCKS_NEEDED1 = 2 }; -#ifdef SOC_EFUSE_SUPPORT_XTS_AES_256_KEYS +#ifdef SOC_FLASH_ENCRYPTION_XTS_AES_256 esp_efuse_purpose_t purpose1[BLOCKS_NEEDED1] = { ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_1, ESP_EFUSE_KEY_PURPOSE_XTS_AES_256_KEY_2, diff --git a/components/soc/esp32c3/include/soc/soc_caps.h b/components/soc/esp32c3/include/soc/soc_caps.h index eef3d9c157..5b54f55865 100644 --- a/components/soc/esp32c3/include/soc/soc_caps.h +++ b/components/soc/esp32c3/include/soc/soc_caps.h @@ -13,6 +13,7 @@ #define SOC_HMAC_SUPPORTED 1 #define SOC_ASYNC_MEMCPY_SUPPORTED 1 #define SOC_USB_SERIAL_JTAG_SUPPORTED 1 +#define SOC_FLASH_ENCRYPTION_XTS_AES 1 /*-------------------------- COMMON CAPS ---------------------------------------*/ #define SOC_SUPPORTS_SECURE_DL_MODE 1 diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h index 535c0bba5f..b0f55e6db9 100644 --- a/components/soc/esp32s2/include/soc/soc_caps.h +++ b/components/soc/esp32s2/include/soc/soc_caps.h @@ -55,6 +55,8 @@ #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3 #define SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS 1 #define SOC_CACHE_SUPPORT_WRAP 1 +#define SOC_FLASH_ENCRYPTION_XTS_AES 1 +#define SOC_FLASH_ENCRYPTION_XTS_AES_256 1 /*-------------------------- ADC CAPS ----------------------------------------*/ #define SOC_ADC_PERIPH_NUM (2) diff --git a/components/soc/esp32s3/include/soc/soc_caps.h b/components/soc/esp32s3/include/soc/soc_caps.h index 05e11a847e..6c62dad022 100644 --- a/components/soc/esp32s3/include/soc/soc_caps.h +++ b/components/soc/esp32s3/include/soc/soc_caps.h @@ -21,8 +21,10 @@ #define SOC_HMAC_SUPPORTED 0 #define SOC_ASYNC_MEMCPY_SUPPORTED 1 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3 -#define SOC_SDMMC_HOST_SUPPORTED 1 #define SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS 1 +#define SOC_SDMMC_HOST_SUPPORTED 1 +#define SOC_FLASH_ENCRYPTION_XTS_AES 1 +#define SOC_FLASH_ENCRYPTION_XTS_AES_256 1 /*-------------------------- ADC CAPS ----------------------------------------*/ diff --git a/docs/en/security/flash-encryption.rst b/docs/en/security/flash-encryption.rst index 0a40ab7778..fb934d1836 100644 --- a/docs/en/security/flash-encryption.rst +++ b/docs/en/security/flash-encryption.rst @@ -49,7 +49,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF .. Comment: As text in cells of list-table header rows does not wrap, it is necessary to make 0 header rows and apply bold typeface to the first row. Otherwise, the table goes beyond the html page limits on the right. -.. only:: esp32 +.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES .. list-table:: eFuses Used in Flash Encryption :widths: 25 40 10 @@ -63,7 +63,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF - 2 * - ``flash_encryption`` (block1) - AES key storage. - - 256 + - 256 bit key block * - ``FLASH_CRYPT_CONFIG`` - Controls the AES encryption process. - 4 @@ -78,7 +78,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF - 7 -.. only:: esp32s2 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 .. list-table:: eFuses Used in Flash Encryption :widths: 25 40 10 @@ -89,7 +89,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF - **Bit Depth** * - ``BLOCK_KEYN`` - AES key storage. N is between 0 and 5. - - 256 + - One 256 bit key block for XTS_AES_128, Two 256 bit key blocks for XTS_AES_256 (512 bit total) * - ``KEY_PURPOSE_N`` - Controls the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. Possible values: ``2`` for ``XTS_AES_256_KEY_1`` , ``3`` for ``XTS_AES_256_KEY_2``, and ``4`` for ``XTS_AES_128_KEY``. Final AES key is derived based on the value of one or two of these purpose eFuses. For a detailed description of the possible combinations, see *{IDF_TARGET_NAME} Technical Reference Manual* > *External Memory Encryption and Decryption (XTS_AES)* [`PDF <{IDF_TARGET_TRM_EN_URL}#extmemencr>`__]. - 4 @@ -100,7 +100,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF - Enables encryption and decryption, when an SPI boot mode is set. Feature is enabled if 1 or 3 bits are set in the eFuse, disabled otherwise. - 3 -.. only:: esp32c3 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 .. list-table:: eFuses Used in Flash Encryption :widths: 25 40 10 @@ -111,7 +111,7 @@ The flash encryption operation is controlled by various eFuses available on {IDF - **Bit Depth** * - ``BLOCK_KEYN`` - AES key storage. N is between 0 and 5. - - 256 + - 256 bit key block * - ``KEY_PURPOSE_N`` - Controls the purpose of eFuse block ``BLOCK_KEYN``, where N is between 0 and 5. For flash encryption the only valid value is ``4`` for ``XTS_AES_128_KEY``. - 4 @@ -134,7 +134,7 @@ Flash Encryption Process Assuming that the eFuse values are in their default states and the firmware bootloader is compiled to support flash encryption, the flash encryption process executes as shown below: -.. only:: esp32 +.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES 1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader. @@ -152,7 +152,7 @@ Assuming that the eFuse values are in their default states and the firmware boot 8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM. -.. only:: esp32s2 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader. @@ -170,7 +170,7 @@ Assuming that the eFuse values are in their default states and the firmware boot 8. The device is then rebooted to start executing the encrypted image. The firmware bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM. -.. only:: esp32c3 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The ROM bootloader loads the firmware bootloader. @@ -285,7 +285,7 @@ To use a host generated key, take the following steps: 2. Generate a random key by running: -.. only:: esp32s2 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 If :ref:`Size of generated AES-XTS key ` is AES-256 (512-bit key) need to use the `XTS_AES_256_KEY_1` and `XTS_AES_256_KEY_2` purposes. The espsecure does not support 512-bit key, but it is possible to workaround: @@ -305,7 +305,7 @@ To use a host generated key, take the following steps: espsecure.py generate_flash_encryption_key my_flash_encryption_key.bin -.. only:: not esp32s2 +.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES_256 .. code-block:: bash @@ -314,13 +314,13 @@ To use a host generated key, take the following steps: 3. **Before the first encrypted boot**, burn the key into your device's eFuse using the command below. This action can be done **only once**. -.. only:: esp32 +.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES .. code-block:: bash espefuse.py --port PORT burn_key flash_encryption my_flash_encryption_key.bin -.. only:: esp32s2 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 .. code-block:: bash @@ -342,7 +342,7 @@ To use a host generated key, take the following steps: espefuse.py --port PORT burn_key BLOCK+1 my_flash_encryption_key2.bin XTS_AES_256_KEY_2 -.. only:: esp32c3 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 .. code-block:: bash @@ -373,7 +373,9 @@ Enabling flash encryption will increase the size of bootloader, which might requ This command will write to flash memory unencrypted images: the firmware bootloader, the partition table and applications. Once the flashing is complete, {IDF_TARGET_NAME} will reset. On the next boot, the firmware bootloader encrypts: the firmware bootloader, application partitions and partitions marked as ``encrypted`` then resets. Encrypting in-place can take time, up to a minute for large partitions. After that, the application is decrypted at runtime and executed. -At this stage, if you need to update and re-flash binaries, see :ref:`encrypt-partitions`. +If using Development Mode, then the easiest way to update and re-flash binaries is :ref:`encrypt-partitions`. + +If using Release Mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext. See :ref:`manual-encryption`. .. _encrypt-partitions: @@ -440,9 +442,9 @@ For subsequent plaintext field updates, use :ref:`OTA scheme ` then you will need to pass the ``--flash_crypt_conf`` argument to ``espsecure.py`` to set the matching value. This will not happen if the device configured flash encryption by itself, but may happen if burning eFuses manually to enable flash encryption. + +The command ``espsecure.py decrypt_flash_data`` can be used with the same options (and different input/output files), to decrypt ciphertext flash contents or a previously encrypted file. + Technical Details ----------------- The following sections provide some reference information about the operation of flash encryption. -.. only:: esp32 +.. only:: not SOC_FLASH_ENCRYPTION_XTS_AES .. _flash-encryption-algorithm: @@ -897,13 +948,13 @@ The following sections provide some reference information about the operation of - To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code. -.. only:: esp32s2 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES_256 .. _flash-encryption-algorithm: Flash Encryption Algorithm ^^^^^^^^^^^^^^^^^^^^^^^^^^ - - {IDF_TARGET_NAME} use the XTS-AES block chiper mode with 256 bit or 512 bit key size for flash encryption. + - {IDF_TARGET_NAME} use the XTS-AES block cipher mode with 256 bit or 512 bit key size for flash encryption. - XTS-AES is a block chiper mode specifically designed for disc encryption and addresses the weaknesses other potential modes (e.g. AES-CTR) have for this use case. A detailed description of the XTS-AES algorithm can be found in `IEEE Std 1619-2007 `_. @@ -911,7 +962,7 @@ The following sections provide some reference information about the operation of - To see the full flash encryption algorithm implemented in Python, refer to the `_flash_encryption_operation()` function in the ``espsecure.py`` source code. -.. only:: esp32c3 +.. only:: SOC_FLASH_ENCRYPTION_XTS_AES and not SOC_FLASH_ENCRYPTION_XTS_AES_256 .. _flash-encryption-algorithm: