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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html>`_

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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html#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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_encryption.html>`_

Detailed explanation of encryption scope: `Encrypted Partitions <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/security/flash-encryption.html#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):

.. list-table:: ESP32 Series Flash Encryption Feature Comparison
    :header-rows: 1

    * - 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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c5/api-reference/system/soc_caps.html#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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s2/security/flash-encryption.html#key-points-about-flash-encryption>`_ `ESP32-C3 Flash Encryption <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/security/flash-encryption.html>`_.

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() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_flash/index.html#_CPPv428esp_flash_encryption_enabledv>`__ to check Flash Encryption status
- Use `esp_get_flash_encryption_mode() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_flash/index.html#_CPPv429esp_get_flash_encryption_modev>`__ to get encryption mode (Development Mode or Release Mode)

For configuration methods, see: `Flash Encryption Settings <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#id4>`_

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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#id3>`_

Application Access to Encrypted Partitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Applications can transparently access encrypted Flash content:

**Reading Encrypted Flash**:

- Use `esp_partition_read() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/storage/partition.html#_CPPv418esp_partition_readPK15esp_partition_t6size_tPv6size_t>`__ or `esp_flash_read_encrypted() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_flash/index.html#_CPPv424esp_flash_read_encryptedP11esp_flash_t8uint32_tPv8uint32_t>`__ to read plaintext content (automatically decrypted)
- Use `esp_flash_read() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_flash/index.html#_CPPv414esp_flash_readP11esp_flash_tPv8uint32_t8uint32_t>`__ to read raw encrypted data (no decryption)

**Writing Encrypted Flash**:

- Use `esp_partition_write() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/storage/partition.html#_CPPv419esp_partition_writePK15esp_partition_t6size_tPKv6size_t>`__ to write plaintext content (automatically encrypted)
- Use `esp_flash_write_encrypted() <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/spi_flash/index.html#_CPPv425esp_flash_write_encryptedP11esp_flash_t8uint32_tPKv8uint32_t>`__ to write raw encrypted content (skips automatic encryption)


For more API details: `Reading/Writing Data in Encrypted Flash <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#reading-writing-content>`_

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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#encrypt-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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#disabling-flash-encryption>`_

Example Code
~~~~~~~~~~~~

For complete Flash Encryption usage examples, please refer to:

- `ESP-IDF Flash Encryption Example <https://github.com/espressif/esp-idf/tree/master/examples/security/flash_encryption>`_
- `Security Features Comprehensive Example <https://github.com/espressif/esp-idf/tree/master/examples/security/security_features_app>`_

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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/security/flash-encryption.html#flash-encrypt-best-practices>`_

Frequently Asked Questions (FAQ)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Please refer to: `ESP-FAQ Security Section <https://docs.espressif.com/projects/esp-faq/en/latest/software-framework/security.html>`_
