Flash Encryption

[中文]

This is a quick start guide to ESP32-C2's flash encryption feature. Using application code as an example, it demonstrates how to test and verify flash encryption operations during development and production.

Note

In this guide, most used commands are in the form of idf.py secure-<command>, which is a wrapper around corresponding espsecure.py <command>. The idf.py based commands provides more user-friendly experience, although may lack some of the advanced functionality of their espsecure.py based counterparts.

Introduction

Flash encryption is intended for encrypting the contents of the ESP32-C2's off-chip flash memory. Once this feature is enabled, firmware is flashed as plaintext, and then the data is encrypted in place on the first boot. As a result, physical readout of flash will not be sufficient to recover most flash contents.

Important

For production use, flash encryption should be enabled in the "Release" mode only.

Important

Enabling flash encryption limits the options for further updates of ESP32-C2. Before using this feature, read the document and make sure to understand the implications.

Encrypted Partitions

With flash encryption enabled, the following types of data are encrypted by default:

Other types of data can be encrypted conditionally:

  • Any partition marked with the encrypted flag in the partition table. For details, see Encrypted Partition Flag.

  • Secure Boot bootloader digest if Secure Boot is enabled (see below).

Relevant eFuses

The flash encryption operation is controlled by various eFuses available on ESP32-C2. The list of eFuses and their descriptions is given in the table below. The names in eFuse column are also used by espefuse.py tool and idf.py based eFuse commands. For usage in the eFuse API, modify the name by adding ESP_EFUSE_, for example: esp_efuse_read_field_bit (ESP_EFUSE_DISABLE_DL_ENCRYPT).

eFuses Used in Flash Encryption

eFuse

Description

Bit Depth

XTS_KEY_LENGTH_256

Controls actual number of eFuse bits used to derive final 256-bit AES key. Possible values: 1 use all 256 bits of the eFuse block for the key, 0 use the lower 128 bits of the eFuse block for the key (the higher 128 bits are reserved for Secure Boot key). For 128 bits option, the final AES key is derived as SHA256(EFUSE_KEY0_FE_128BIT).

1

BLOCK_KEY0

AES key storage

256 or 128 key block

DIS_DOWNLOAD_MANUAL_ENCRYPT

If set, disable flash encryption when in download bootmodes.

1

SPI_BOOT_CRYPT_CNT

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

Note

  • R/W access control is available for all the eFuse bits listed in the table above.

  • The default value of these bits is 0 after manufacturing.

Read and write access to eFuse bits is controlled by appropriate fields in the registers WR_DIS and RD_DIS. For more information on ESP32-C2 eFuses, see eFuse manager. To change protection bits of eFuse field using idf.py, use these two commands: efuse-read-protect and efuse-write-protect (idf.py based aliases of espefuse.py commands write_protect_efuse and read_protect_efuse). Example idf.py efuse-write-protect DISABLE_DL_ENCRYPT.

Important

ESP32-C2 has only one eFuse key block for both keys: Secure Boot and Flash Encryption. As the eFuse key block can only be burned once, these keys should be burned together at the same time. Please note that "Secure Boot" and "Flash Encryption" can not be enabled separately as subsequent writes to eFuse key block shall return an error.

Flash Encryption Process

Assuming that the eFuse values are in their default states and the second stage bootloader is compiled to support flash encryption, the flash encryption process executes as shown below:

  1. On the first power-on reset, all data in flash is un-encrypted (plaintext). The first stage (ROM) bootloaders loads the second stage bootloader.

  2. The second stage bootloader reads the SPI_BOOT_CRYPT_CNT eFuse value (0b000). Since the value is 0 (even number of bits set), it configures and enables the flash encryption block. For more information on the flash encryption block, see ESP32-C2 Technical Reference Manual.

  3. The second stage bootloader uses RNG (random) module to generate an 256 or 128 bit key (depends on Size of generated XTS-AES key) and then writes it into BLOCK_KEY0 eFuse. The software also updates the XTS_KEY_LENGTH_256 according to the chosen option. The key cannot be accessed via software as the write and read protection bits for BLOCK_KEY0 eFuse are set. The flash encryption operations happen entirely by hardware, and the key cannot be accessed via software. If 128-bit flash encryption key is used, then only the lower 128 bits of the eFuse key block are read-protected, the remaining 128 bits are readable, which is required for secure boot. The entire eFuse block is write-protected. If the FE key is 256 bits long, then XTS_KEY_LENGTH_256 is 1, otherwise it is 0. To prevent this eFuse from being accidentally changed in the future (from 0 to 1), we set a write-protect bit for the RELEASE mode. If a valid key is already present in the eFuse (e.g., burned using espefuse tool) then the process of key generation is skipped and the same key is used for flash encryption process.

  4. Flash encryption block encrypts the flash contents - the second stage bootloader, applications and partitions marked as encrypted. Encrypting in-place can take time, up to a minute for large partitions.

  5. The second stage bootloader sets the first available bit in SPI_BOOT_CRYPT_CNT (0b001) to mark the flash contents as encrypted. Odd number of bits is set.

  6. For Development Mode, the second stage bootloader allows the UART bootloader to re-flash encrypted binaries. Also, the SPI_BOOT_CRYPT_CNT eFuse bits are NOT write-protected. In addition, the second stage bootloader by default sets the eFuse bits DIS_DOWNLOAD_ICACHE, DIS_PAD_JTAG, and DIS_DIRECT_BOOT.

  7. For Release Mode, the second stage bootloader sets all the eFuse bits set under development mode as well as DIS_DOWNLOAD_MANUAL_ENCRYPT. It also write-protects the SPI_BOOT_CRYPT_CNT eFuse bits. To modify this behavior, see Enabling UART Bootloader Encryption/Decryption.

  8. The device is then rebooted to start executing the encrypted image. The second stage bootloader calls the flash decryption block to decrypt the flash contents and then loads the decrypted contents into IRAM.

During the development stage, there is a frequent need to program different plaintext flash images and test the flash encryption process. This requires that Firmware Download mode is able to load new plaintext images as many times as it might be needed. However, during manufacturing or production stages, Firmware Download mode should not be allowed to access flash contents for security reasons.

Hence, two different flash encryption configurations were created: for development and for production. For details on these configurations, see Section Flash Encryption Configuration.

Flash Encryption Configuration

The following flash encryption modes are available:

  • Development Mode - recommended for use only during development. In this mode, it is still possible to flash new plaintext firmware to the device, and the bootloader will transparently encrypt this firmware using the key stored in hardware. This allows, indirectly, to read out the plaintext of the firmware in flash.

  • Release Mode - recommended for manufacturing and production. In this mode, flashing plaintext firmware to the device without knowing the encryption key is no longer possible.

This section provides information on the mentioned flash encryption modes and step by step instructions on how to use them.

Development Mode

During development, you can encrypt flash using either an ESP32-C2 generated key or external host-generated key.

Using ESP32-C2 Generated Key

Development mode allows you to download multiple plaintext images using Firmware Download mode.

To test flash encryption process, take the following steps:

  1. Ensure that you have an ESP32-C2 device with default flash encryption eFuse settings as shown in Relevant eFuses.

  1. In Project Configuration Menu, do the following:

Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.

  1. Run the command given below to build and flash the complete images.

idf.py flash monitor

Note

This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.

This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, ESP32-C2 will reset. On the next boot, the second stage bootloader encrypts: the second stage 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.

A sample output of the first ESP32-C2 boot after enabling flash encryption is given below:

ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x1 (POWERON),boot:0xc (SPI_FAST_FLASH_BOOT)
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (21) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (21) boot: compile time 19:36:15
I (21) boot: chip revision: 0
I (24) boot.esp32c2: MMU Page Size  : 64K
I (29) boot.esp32c2: SPI Speed      : 60MHz
I (34) boot.esp32c2: SPI Mode       : DIO
I (39) boot.esp32c2: SPI Flash Size : 2MB
I (43) boot: Enabling RNG early entropy source...
I (49) boot: Partition Table:
I (52) boot: ## Label            Usage          Type ST Offset   Length
I (60) boot:  0 nvs              WiFi data        01 02 00010000 00006000
I (67) boot:  1 phy_init         RF data          01 01 00016000 00001000
I (75) boot:  2 factory          factory app      00 00 00020000 00100000
I (82) boot: End of partition table
I (86) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (101) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h (  5168) load
I (104) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (120) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (134) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h (  5888) load
I (139) boot: Loaded app from partition at offset 0x20000
I (139) boot: Checking flash encryption...
I (142) efuse: Batch mode of writing fields is enabled
I (148) flash_encrypt: Generating new flash encryption key...
I (155) efuse: Writing EFUSE_BLK_KEY0 with purpose 1
W (161) flash_encrypt: Not disabling UART bootloader encryption
I (167) flash_encrypt: Disable UART bootloader cache...
I (175) flash_encrypt: Disable JTAG...
I (190) efuse: BURN BLOCK3
I (195) efuse: BURN BLOCK3 - OK (write block == read block)
I (204) efuse: BURN BLOCK0
I (208) efuse: BURN BLOCK0 - OK (write block == read block)
I (213) efuse: Batch mode. Prepared fields are committed
I (219) esp_image: segment 0: paddr=00000020 vaddr=3fcd6190 size=02a84h ( 10884)
I (229) esp_image: segment 1: paddr=00002aac vaddr=403ae000 size=00830h (  2096)
I (236) esp_image: segment 2: paddr=000032e4 vaddr=403b0000 size=042a0h ( 17056)
I (679) flash_encrypt: bootloader encrypted successfully
I (731) flash_encrypt: partition table encrypted and loaded successfully
I (731) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (741) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h (  5168)
I (745) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632)
I (759) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (774) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h (  5888)
I (776) flash_encrypt: Encrypting partition 2 at offset 0x20000 (length 0x100000)...
I (6429) flash_encrypt: Done encrypting
I (6429) efuse: BURN BLOCK0
I (6432) efuse: BURN BLOCK0 - OK (all write block bits are set)
I (6438) flash_encrypt: Flash encryption completed
I (6443) boot: Resetting with flash encryption enabled...

A sample output of subsequent ESP32-C2 boots just mentions that flash encryption is already enabled:

ESP-ROM:esp8684-api1-20211015
Build:Oct 15 2021
rst:0x3 (RTC_SW_SYS_RST),boot:0xc (SPI_FAST_FLASH_BOOT)
Saved PC:0x403b0f9e
SPIWP:0xee
mode:DIO, clock div:1
load:0x3fcd6190,len:0x2a84
load:0x403ae000,len:0x830
load:0x403b0000,len:0x42a0
entry 0x403ae000
I (23) boot: ESP-IDF v5.0-dev-2717-g0d1e015-dirty 2nd stage bootloader
I (23) boot: compile time 19:36:15
I (23) boot: chip revision: 0
I (27) boot.esp32c2: MMU Page Size  : 64K
I (32) boot.esp32c2: SPI Speed      : 60MHz
I (36) boot.esp32c2: SPI Mode       : DIO
I (41) boot.esp32c2: SPI Flash Size : 2MB
I (46) boot: Enabling RNG early entropy source...
I (51) boot: Partition Table:
I (55) boot: ## Label            Usage          Type ST Offset   Length
I (62) boot:  0 nvs              WiFi data        01 02 00010000 00006000
I (70) boot:  1 phy_init         RF data          01 01 00016000 00001000
I (77) boot:  2 factory          factory app      00 00 00020000 00100000
I (85) boot: End of partition table
I (89) esp_image: segment 0: paddr=00020020 vaddr=3c010020 size=06858h ( 26712) map
I (103) esp_image: segment 1: paddr=00026880 vaddr=3fca9a60 size=01430h (  5168) load
I (107) esp_image: segment 2: paddr=00027cb8 vaddr=40380000 size=08360h ( 33632) load
I (123) esp_image: segment 3: paddr=00030020 vaddr=42000020 size=0f67ch ( 63100) map
I (138) esp_image: segment 4: paddr=0003f6a4 vaddr=40388360 size=01700h (  5888) load
I (143) boot: Loaded app from partition at offset 0x20000
I (143) boot: Checking flash encryption...
I (146) flash_encrypt: flash encryption is enabled (1 plaintext flashes left)
I (154) boot: Disabling RNG early entropy source...
I (171) cpu_start: Pro cpu up.
I (179) cpu_start: Pro cpu start user code
I (179) cpu_start: cpu freq: 120000000 Hz
I (179) cpu_start: Application information:
I (182) cpu_start: Project name:     hello_world
I (187) cpu_start: App version:      v5.0-dev-2717-g0d1e015-dirty
I (194) cpu_start: Compile time:     May 20 2022 19:35:55
I (200) cpu_start: ELF file SHA256:  04592ac3c9304cdc...
I (206) cpu_start: ESP-IDF:          v5.0-dev-2717-g0d1e015-dirty
I (213) heap_init: Initializing. RAM available for dynamic allocation:
I (220) heap_init: At 3FCABCB0 len 0002C350 (176 KiB): D/IRAM
I (226) heap_init: At 3FCD8000 len 0000742C (29 KiB): STACK/DRAM
I (234) spi_flash: detected chip: generic
I (238) spi_flash: flash io: dio
W (242) flash_encrypt: Flash encryption mode is DEVELOPMENT (not secure)
I (249) sleep: Configure to isolate all GPIO pins in sleep state
I (256) sleep: Enable automatic switching of GPIO sleep configuration
W (263) INT_WDT: ESP32-C2 only has one timer group
I (268) cpu_start: Starting scheduler.
Hello world!
This is esp32c2 chip with 1 CPU core(s), WiFi/BLE, silicon revision 0, 2MB external flash
Minimum free heap size: 195052 bytes

FLASH_CRYPT_CNT eFuse value is 1
Flash encryption feature is enabled in DEVELOPMENT mode

At this stage, if you need to update and re-flash binaries, see Re-flashing Updated Partitions.

Using Host Generated Key

It is possible to pre-generate a flash encryption key on the host computer and burn it into the eFuse. This allows you to pre-encrypt data on the host and flash already encrypted data without needing a plaintext flash update. This feature can be used in both Development Mode and Release Mode. Without a pre-generated key, data is flashed in plaintext and then ESP32-C2 encrypts the data in-place.

Note

This option is not recommended for production, unless a separate key is generated for each individual device.

Note

Note that ESP32-C2 only has one eFuse key block for both Secure Boot and Flash Encryption keys. Therefore, writing the host-generated Flash Encryption key must be done with Secure Boot key (if used), otherwise Secure Boot cannot be used.

To use a host generated key, take the following steps:

  1. Ensure that you have an ESP32-C2 device with default flash encryption eFuse settings as shown in Relevant eFuses.

  1. Generate a random key by running:

If Size of generated XTS-AES key is AES-128 (256-bit key):

idf.py secure-generate-flash-encryption-key my_flash_encryption_key.bin

else if Size of generated XTS-AES key is AES-128 key derived from 128 bits (SHA256(128 bits)):

idf.py secure-generate-flash-encryption-key --keylen 128 my_flash_encryption_key.bin

  1. Before the first encrypted boot, burn the key into your device's eFuse using the command below. This action can be done only once.

For AES-128 (256-bit key) - XTS_AES_128_KEY (the XTS_KEY_LENGTH_256 eFuse will be burn to 1):

idf.py --port PORT efuse-burn-key BLOCK_KEY0 flash_encryption_key256.bin XTS_AES_128_KEY

For AES-128 key derived from 128 bits (SHA256(128 bits)) - XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS. The FE key will be written in the lower part of eFuse BLOCK_KEY0. The upper 128 bits are not used and will remain available for reading by software. Using the special mode of the espefuse tool, shown in the For burning both keys together section below, the user can write their data to it using any espefuse commands.

idf.py --port PORT efuse-burn-key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS

For burning both keys together (Secure Boot and Flash Encryption):

espefuse.py --port PORT --chip esp32c2 burn_key_digest secure_boot_signing_key.pem \
                                        burn_key BLOCK_KEY0 flash_encryption_key128.bin XTS_AES_128_KEY_DERIVED_FROM_128_EFUSE_BITS

If the key is not burned and the device is started after enabling flash encryption, the ESP32-C2 will generate a random key that software cannot access or modify.

  1. In Project Configuration Menu, do the following:

Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.

  1. Run the command given below to build and flash the complete images.

idf.py flash monitor

Note

This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.

This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, ESP32-C2 will reset. On the next boot, the second stage bootloader encrypts: the second stage 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.

If using Development Mode, then the easiest way to update and re-flash binaries is Re-flashing Updated Partitions.

If using Release Mode, then it is possible to pre-encrypt the binaries on the host and then flash them as ciphertext. See Manually Encrypting Files.

Re-flashing Updated Partitions

If you update your application code (done in plaintext) and want to re-flash it, you will need to encrypt it before flashing. To encrypt the application and flash it in one step, run:

idf.py encrypted-app-flash monitor

If all partitions needs to be updated in encrypted format, run:

idf.py encrypted-flash monitor

Release Mode

In Release mode, UART bootloader cannot perform flash encryption operations. New plaintext images can ONLY be downloaded using the over-the-air (OTA) scheme which will encrypt the plaintext image before writing to flash.

To use this mode, take the following steps:

  1. Ensure that you have an ESP32-C2 device with default flash encryption eFuse settings as shown in Relevant eFuses.

  1. In Project Configuration Menu, do the following:

Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.

  1. Run the command given below to build and flash the complete images.

idf.py flash monitor

Note

This command does not include any user files which should be written to the partitions on the flash memory. Please write them manually before running this command otherwise the files should be encrypted separately before writing.

This command will write to flash memory unencrypted images: the second stage bootloader, the partition table and applications. Once the flashing is complete, ESP32-C2 will reset. On the next boot, the second stage bootloader encrypts: the second stage 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.

Once the flash encryption is enabled in Release mode, the bootloader will write-protect the SPI_BOOT_CRYPT_CNT eFuse.

For subsequent plaintext field updates, use OTA scheme.

Note

If you have pre-generated the flash encryption key and stored a copy, and the UART download mode is not permanently disabled via CONFIG_SECURE_UART_ROM_DL_MODE , then it is possible to update the flash locally by pre-encrypting the files and then flashing the ciphertext. See Manually Encrypting Files.

Best Practices

When using Flash Encryption in production:

  • Do not reuse the same flash encryption key between multiple devices. This means that an attacker who copies encrypted data from one device cannot transfer it to a second device.

  • The UART ROM Download Mode should be disabled entirely if it is not needed, or permanently set to "Secure Download Mode" otherwise. Secure Download Mode permanently limits the available commands to updating SPI config, changing baud rate, basic flash write, and returning a summary of the currently enabled security features with the get_security_info command. The default behaviour is to set Secure Download Mode on first boot in Release mode. To disable Download Mode entirely, select CONFIG_SECURE_UART_ROM_DL_MODE to "Permanently disable ROM Download Mode (recommended)" or call esp_efuse_disable_rom_download_mode() at runtime.

  • Enable Secure Boot as an extra layer of protection, and to prevent an attacker from selectively corrupting any part of the flash before boot.

Enable Flash Encryption Externally

In the process mentioned above, flash encryption related eFuses which ultimately enable flash encryption are programmed through the second stage bootloader. Alternatively, all the eFuses can be programmed with the help of espefuse tool. Please refer Enable Flash Encryption Externally for more details.

Possible Failures

Once flash encryption is enabled, the SPI_BOOT_CRYPT_CNT eFuse value will have an odd number of bits set. It means that all the partitions marked with the encryption flag are expected to contain encrypted ciphertext. Below are the three typical failure cases if the ESP32-C2 is erroneously loaded with plaintext data:

  1. If the bootloader partition is re-flashed with a plaintext second stage bootloader image, the first stage (ROM) bootloader will fail to load the second stage bootloader resulting in the following failure:

rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b
invalid header: 0xb414f76b

Note

The value of invalid header will be different for every application.

Note

This error also appears if the flash contents are erased or corrupted.

  1. If the second stage bootloader is encrypted, but the partition table is re-flashed with a plaintext partition table image, the bootloader will fail to read the partition table resulting in the following failure:

rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0018,len:4
load:0x3fff001c,len:10464
ho 0 tail 12 room 4
load:0x40078000,len:19168
load:0x40080400,len:6664
entry 0x40080764
I (60) boot: ESP-IDF v4.0-dev-763-g2c55fae6c-dirty 2nd stage bootloader
I (60) boot: compile time 19:15:54
I (62) boot: Enabling RNG early entropy source...
I (67) boot: SPI Speed      : 40MHz
I (72) boot: SPI Mode       : DIO
I (76) boot: SPI Flash Size : 4MB
E (80) flash_parts: partition 0 invalid magic number 0x94f6
E (86) boot: Failed to verify partition table
E (91) boot: load partition table error!

  1. If the bootloader and partition table are encrypted, but the application is re-flashed with a plaintext application image, the bootloader will fail to load the application resulting in the following failure:

rst:0x3 (SW_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0018,len:4
load:0x3fff001c,len:8452
load:0x40078000,len:13616
load:0x40080400,len:6664
entry 0x40080764
I (56) boot: ESP-IDF v4.0-dev-850-gc4447462d-dirty 2nd stage bootloader
I (56) boot: compile time 15:37:14
I (58) boot: Enabling RNG early entropy source...
I (64) boot: SPI Speed      : 40MHz
I (68) boot: SPI Mode       : DIO
I (72) boot: SPI Flash Size : 4MB
I (76) boot: Partition Table:
I (79) boot: ## Label            Usage          Type ST Offset   Length
I (87) boot:  0 nvs              WiFi data        01 02 0000a000 00006000
I (94) boot:  1 phy_init         RF data          01 01 00010000 00001000
I (102) boot:  2 factory          factory app      00 00 00020000 00100000
I (109) boot: End of partition table
E (113) esp_image: image at 0x20000 has invalid magic byte
W (120) esp_image: image at 0x20000 has invalid SPI mode 108
W (126) esp_image: image at 0x20000 has invalid SPI size 11
E (132) boot: Factory app partition is not bootable
E (138) boot: No bootable app partitions in the partition table

ESP32-C2 Flash Encryption Status

  1. Ensure that you have an ESP32-C2 device with default flash encryption eFuse settings as shown in Relevant eFuses.

To check if flash encryption on your ESP32-C2 device is enabled, do one of the following:

  • flash the application example security/flash_encryption onto your device. This application prints the SPI_BOOT_CRYPT_CNT eFuse value and if flash encryption is enabled or disabled.

  • Find the serial port name under which your ESP32-C2 device is connected, replace PORT with your port name in the following command, and run it:

    idf.py efuse-summary

Reading and Writing Data in Encrypted Flash

ESP32-C2 application code can check if flash encryption is currently enabled by calling esp_flash_encryption_enabled(). Also, a device can identify the flash encryption mode by calling esp_get_flash_encryption_mode().

Once flash encryption is enabled, be more careful with accessing flash contents from code.

Scope of Flash Encryption

Whenever the SPI_BOOT_CRYPT_CNT eFuse is set to a value with an odd number of bits, all flash content accessed via the MMU's flash cache is transparently decrypted. It includes:

  • Executable application code in flash (IROM).

  • All read-only data stored in flash (DROM).

  • Any data accessed via spi_flash_mmap().

  • The second stage bootloader image when it is read by the first stage (ROM) bootloader.

Important

The MMU flash cache unconditionally decrypts all existing data. Data which is stored unencrypted in flash memory will also be "transparently decrypted" via the flash cache and will appear to software as random garbage.

Reading from Encrypted Flash

To read data without using a flash cache MMU mapping, you can use the partition read function esp_partition_read(). This function will only decrypt data when it is read from an encrypted partition. Data read from unencrypted partitions will not be decrypted. In this way, software can access encrypted and non-encrypted flash in the same way.

You can also use the following SPI flash API functions:

Data stored using the Non-Volatile Storage (NVS) API is always stored and read decrypted from the perspective of flash encryption. It is up to the library to provide encryption feature if required. Refer to NVS Encryption for more details.

Writing to Encrypted Flash

It is recommended to use the partition write function esp_partition_write(). This function will only encrypt data when it is written to an encrypted partition. Data written to unencrypted partitions will not be encrypted. In this way, software can access encrypted and non-encrypted flash in the same way.

You can also pre-encrypt and write data using the function esp_flash_write_encrypted()

Also, the following ROM function exist but not supported in esp-idf applications:

  • esp_rom_spiflash_write_encrypted pre-encrypts and writes data to flash

  • SPIWrite writes unencrypted data to flash

Since data is encrypted in blocks, the minimum write size for encrypted data is 16 bytes and the alignment is also 16 bytes.

Updating Encrypted Flash

OTA Updates

OTA updates to encrypted partitions will automatically write encrypted data if the function esp_partition_write() is used.

Before building the application image for OTA updating of an already encrypted device, enable the option Enable flash encryption on boot in project configuration menu.

For general information about ESP-IDF OTA updates, please refer to OTA.

Updating Encrypted Flash via Serial

Flashing an encrypted device via serial bootloader requires that the serial bootloader download interface has not been permanently disabled via eFuse.

In Development Mode, the recommended method is Re-flashing Updated Partitions.

In Release Mode, if a copy of the same key stored in eFuse is available on the host then it is possible to pre-encrypt files on the host and then flash them. See Manually Encrypting Files.

Disabling Flash Encryption

If flash encryption was enabled accidentally, flashing of plaintext data will soft-brick the ESP32-C2. The device will reboot continuously, printing the error flash read err, 1000 or invalid header: 0xXXXXXX.

For flash encryption in Development mode, encryption can be disabled by burning the SPI_BOOT_CRYPT_CNT eFuse. It can only be done one time per chip by taking the following steps:

  1. In Project Configuration Menu, disable Enable flash encryption on boot, then save and exit.

  2. Open project configuration menu again and double-check that you have disabled this option! If this option is left enabled, the bootloader will immediately re-enable encryption when it boots.

  3. With flash encryption disabled, build and flash the new bootloader and application by running idf.py flash.

  4. Use idf.py to disable the SPI_BOOT_CRYPT_CNT by running:

idf.py efuse-burn SPI_BOOT_CRYPT_CNT

Reset the ESP32-C2. Flash encryption will be disabled, and the bootloader will boot as usual.

Key Points About Flash Encryption

  • Flash memory contents is encrypted using XTS-AES-128. The flash encryption key is 256 or 128 bits and stored in BLOCK_KEY0 eFuse internal to the chip and, by default, is protected from software access.

  • Flash access is transparent via the flash cache mapping feature of ESP32-C2 - any flash regions which are mapped to the address space will be transparently decrypted when read.

    Some data partitions might need to remain unencrypted for ease of access or might require the use of flash-friendly update algorithms which are ineffective if the data is encrypted. NVS partitions for non-volatile storage cannot be encrypted since the NVS library is not directly compatible with flash encryption. For details, refer to NVS Encryption.

  • If flash encryption might be used in future, the programmer must keep it in mind and take certain precautions when writing code that uses encrypted flash.

  • If secure boot is enabled, re-flashing the bootloader of an encrypted device requires a "Re-flashable" secure boot digest (see Flash Encryption and Secure Boot).

Enabling flash encryption will increase the size of bootloader, which might require updating partition table offset. See Bootloader Size.

Important

Do not interrupt power to the ESP32-C2 while the first boot encryption pass is running. If power is interrupted, the flash contents will be corrupted and will require flashing with unencrypted data again. In this case, re-flashing will not count towards the flashing limit.

Limitations of Flash Encryption

Flash encryption protects firmware against unauthorised readout and modification. It is important to understand the limitations of the flash encryption feature:

  • Flash encryption is only as strong as the key. For this reason, we recommend keys are generated on the device during first boot (default behaviour). If generating keys off-device, ensure proper procedure is followed and do not share the same key between all production devices.

  • Not all data is stored encrypted. If storing data on flash, check if the method you are using (library, API, etc.) supports flash encryption.

  • Flash encryption does not prevent an attacker from understanding the high-level layout of the flash. This is because the same AES key is used for every pair of adjacent 16 byte AES blocks. When these adjacent 16 byte blocks contain identical content (such as empty or padding areas), these blocks will encrypt to produce matching pairs of encrypted blocks. This may allow an attacker to make high-level comparisons between encrypted devices (i.e., to tell if two devices are probably running the same firmware version).

  • Flash encryption alone may not prevent an attacker from modifying the firmware of the device. To prevent unauthorised firmware from running on the device, use flash encryption in combination with Secure Boot.

Flash Encryption and Secure Boot

It is recommended to use flash encryption in combination with Secure Boot. However, if Secure Boot is enabled, additional restrictions apply to device re-flashing:

  • OTA Updates are not restricted, provided that the new app is signed correctly with the Secure Boot signing key.

Advanced Features

The following section covers advanced features of flash encryption.

Encrypted Partition Flag

Some partitions are encrypted by default. Other partitions can be marked in the partition table description as requiring encryption by adding the flag encrypted to the partitions' flag field. As a result, data in these marked partitions will be treated as encrypted in the same manner as an app partition.

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x6000
phy_init, data, phy,     0xf000,  0x1000
factory,  app,  factory, 0x10000, 1M
secret_data, 0x40, 0x01, 0x20000, 256K, encrypted

For details on partition table description, see partition table.

Further information about encryption of partitions:

  • Default partition tables do not include any encrypted data partitions.

  • With flash encryption enabled, the app partition is always treated as encrypted and does not require marking.

  • If flash encryption is not enabled, the flag "encrypted" has no effect.

  • You can also consider protecting phy_init data from physical access, readout, or modification, by marking the optional phy partition with the flag encrypted.

  • The nvs partition cannot be encrypted, because the NVS library is not directly compatible with flash encryption.

Enabling UART Bootloader Encryption/Decryption

On the first boot, the flash encryption process burns by default the following eFuses:

  • DIS_DOWNLOAD_MANUAL_ENCRYPT which disables flash encryption operation when running in UART bootloader boot mode.

  • DIS_DOWNLOAD_ICACHE which disables the entire MMU flash cache when running in UART bootloader mode.

  • DIS_DIRECT_BOOT (old name DIS_LEGACY_SPI_BOOT) which disables direct boot mode

However, before the first boot you can choose to keep any of these features enabled by burning only selected eFuses and write-protect the rest of eFuses with unset value 0. For example:

idf.py --port PORT efuse-burn DIS_DOWNLOAD_MANUAL_ENCRYPT
idf.py --port PORT efuse-write-protect DIS_DOWNLOAD_MANUAL_ENCRYPT

Note

Set all appropriate bits before write-protecting!

Write protection of all the three eFuses is controlled by one bit. It means that write-protecting one eFuse bit will inevitably write-protect all unset eFuse bits.

Write protecting these eFuses to keep them unset is not currently very useful, as esptool.py does not support reading encrypted flash.

JTAG Debugging

By default, when Flash Encryption is enabled (in either Development or Release mode) then JTAG debugging is disabled via eFuse. The bootloader does this on first boot, at the same time it enables flash encryption.

See JTAG with Flash Encryption or Secure Boot for more information about using JTAG Debugging with Flash Encryption.

Manually Encrypting Files

Manually encrypting or decrypting files requires the flash encryption key to be pre-burned in eFuse (see Using Host Generated Key) and a copy to be kept on the host. If the flash encryption is configured in Development Mode then it is not necessary to keep a copy of the key or follow these steps, the simpler Re-flashing Updated Partitions steps can be used.

The key file should be a single raw binary file (example: key.bin).

For example, these are the steps to encrypt the file my-app.bin to flash at offset 0x10000. Run idf.py as follows:

idf.py secure-encrypt-flash-data --aes-xts --keyfile /path/to/key.bin --address 0x10000 --output my-app-ciphertext.bin my-app.bin

The file my-app-ciphertext.bin can then be flashed to offset 0x10000 using esptool.py. To see all of the command line options recommended for esptool.py, see the output printed when idf.py build succeeds.

Note

If the flashed ciphertext file is not recognized by the ESP32-C2 when it boots, check that the keys match and that the command line arguments match exactly, including the correct offset.

The command idf.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.

Flash Encryption Algorithm

  • ESP32-C2 use the XTS-AES block cipher mode with 256 bit size for flash encryption. In case the 128-bit key is stored in the eFuse key block, the final 256-bit AES key is obtained as SHA256(EFUSE_KEY0_FE_128BIT).

  • XTS-AES is a block cipher 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.

  • 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.

Was this page helpful?