Flash Encryption

Flash Encryption is an important security feature of ESP32 series chips, used to protect the confidentiality of firmware and data stored in external Flash. When Flash Encryption is enabled, the content in Flash is transparently encrypted, preventing plaintext firmware and data from being obtained through physical reading.

Key features of Flash Encryption:

• Transparent encryption and decryption: Automatic handling of encryption/decryption when accessed through MMU cache

• Hardware implementation: Encryption keys are stored in eFuse and cannot be directly accessed by software

• XTS-AES algorithm: Uses a secure encryption algorithm designed specifically for storage devices

• Selective partition encryption: Specific partition types can be designated for encryption

For more detailed information, refer to: ESP-IDF Flash Encryption Documentation

Flash Encryption and Secure Boot

Flash Encryption and Secure Boot are complementary security features:

• Flash Encryption: Protects data confidentiality, prevents reading Flash contents

• Secure Boot: Ensures code integrity, prevents running unauthorized firmware

It is recommended to enable both features in production environments for optimal security protection. For details, refer to: Flash Encryption and Secure Boot

Encryption Scope

Flash Encryption automatically encrypts the following content:

• Second-stage bootloader

• All app-type partitions

• Partition table

• NVS key partition

• Partitions marked as “encrypted” by the user

Important Note: NVS partition encryption and Flash Encryption are two independent features. NVS encryption feature should be used. See: NVS Encryption Documentation

Detailed explanation of encryption scope: Encrypted Partitions

Flash Encryption Feature Support List

The following is a comparison table of Flash Encryption features for ESP32 series chips, including encryption algorithms, key length/type, hardware support, key storage method, and key source (simplified description):

ESP32 Series Flash Encryption Feature Comparison

Chip Model	Supported Encryption Algorithms	Key Length/Type	Hardware Acceleration/Support	Key Storage Method	Key Source
ESP32	AES-256 (custom implementation)	256-bit	Yes	eFuse	Hardware random number generation
ESP32-S2	XTS-AES-128, XTS-AES-256	256-bit or 512-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation
ESP32-S3	XTS-AES-128, XTS-AES-256	256-bit or 512-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation
ESP32-C2	XTS-AES-128	256-bit	Yes	eFuse (BLOCK_KEY0)	Hardware random number or host generation
ESP32-C3	XTS-AES-128	256-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation
ESP32-C5	XTS-AES-128	256-bit	Yes	eFuse (BLOCK_KEYN) or Key Manager	Hardware random number, host generation, or Key Manager
ESP32-C6	XTS-AES-128	256-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation
ESP32-H2	XTS-AES-128	256-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation
ESP32-P4	XTS-AES-128, XTS-AES-256	256-bit or 512-bit	Yes	eFuse (BLOCK_KEYN)	Hardware random number or host generation

Notes: - ESP32-C5 supports Key Manager as a key source and storage method ESP32-C5 SoC Capability Macros. - Other chips use eFuse storage, and keys can be generated by hardware random number or by the host and then burned ESP32-S2 Flash Encryption ESP32-C3 Flash Encryption.

Development Mode and Release Mode

Flash Encryption provides two modes:

Development Mode

• Allows multiple burnings of plaintext firmware

• Bootloader automatically handles encryption

• Suitable for development and testing phases

• Relatively lower security

Release Mode

• Disables plaintext firmware burning

• Can only update plaintext firmware through OTA

• Suitable for production environments

• Provides maximum security

Status Check:

• Use esp_flash_encryption_enabled() to check Flash Encryption status

• Use esp_get_flash_encryption_mode() to get encryption mode (Development Mode or Release Mode)

For configuration methods, see: Flash Encryption Settings

Encryption Process

The basic process of Flash Encryption:

1. First Boot: Detect eFuse status, initiate encryption process

2. Key Generation: Generate random encryption key and store it in eFuse (can be skipped, supports burning custom keys)

3. In-Place Encryption: Encrypt the content of specified partitions in Flash

4. Set Flag: Mark Flash Encryption as enabled

5. Restart System: Begin normal encrypted mode operation

For a complete explanation of the encryption process: The Flash Encryption Process

Application Access to Encrypted Partitions

Applications can transparently access encrypted Flash content:

Reading Encrypted Flash:

• Use esp_partition_read() or esp_flash_read_encrypted() to read plaintext content (automatically decrypted)

• Use esp_flash_read() to read raw encrypted data (no decryption)

Writing Encrypted Flash:

• Use esp_partition_write() to write plaintext content (automatically encrypted)

• Use esp_flash_write_encrypted() to write raw encrypted content (skips automatic encryption)

For more API details: Reading/Writing Data in Encrypted Flash

Reflashing Flash

In Development Mode:

• Use idf.py encrypted-app-flash to burn new application plaintext, which will be automatically encrypted during burning

• Use idf.py encrypted-flash to burn all partition plaintext, which will be automatically encrypted during burning

In Release Mode:

• Can only update plaintext firmware through OTA

• Can only manually burn ciphertext firmware (only supported when UART ROM Downloads is enabled)

For detailed information: Reflashing Updated Partitions

Disabling Encryption

Supported only in Development Mode (cannot be disabled in Release Mode): Disable Flash Encryption by burning eFuse SPI_BOOT_CRYPT_CNT while in encrypted state.

Warning: Each chip has a limited number of encryption toggle times, typically 3 times (off->on->off->on). Please operate with caution.

For detailed steps: Disabling Flash Encryption

Example Code

For complete Flash Encryption usage examples, please refer to:

• ESP-IDF Flash Encryption Example

• Security Features Comprehensive Example

These examples demonstrate:

• Flash Encryption status check

• Encrypted partition read/write operations

• NVS and FATFS usage in encrypted environments

• Configuration methods for Development Mode and Release Mode

Best Practices

1. Use Release Mode for production environments

2. Use unique keys for each device

3. Use in conjunction with Secure Boot

4. Plan partition encryption strategy reasonably

5. Test OTA update process

For more best practices: Flash Encryption Best Practices

Frequently Asked Questions (FAQ)

• Please refer to: ESP-FAQ Security Section

Provide feedback about this document