How to Decrypt Binary Code from ESP32 Encrypted Flash Memory

Why and When You Need to Decrypt Binary Code on the ESP32

When you enable hardware flash encryption on an ESP32, the chip's AES-256 accelerator encrypts the firmware on the fly as it writes to the external SPI flash. This is excellent for protecting intellectual property in production, but it creates a massive headache when a device fails in the field and you need to analyze the firmware state. To perform failure analysis or debug a bricked unit, you must extract and decrypt binary code from the flash chip back into readable plaintext.

This guide walks through the exact procedure to dump the encrypted flash contents and decrypt binary code using the ESP-IDF toolchain. We are specifically targeting the ESP32-DevKitC V4 board equipped with the ESP32-WROOM-32E module, which features 4MB of external SPI flash and hardware efuse key storage.

Hardware and Software Requirements

Before attempting to read the flash, ensure your bench is set up with the correct hardware. Relying on the onboard USB-to-UART bridge is usually fine, but for low-level debugging where the main chip is partially bricked, an external adapter is mandatory.

Step-by-Step: Dumping and Decrypting the Flash Binary

To decrypt binary code, we first need to dump the raw encrypted hex from the SPI flash, then use the device's unique AES key (stored in the efuse) to reverse the encryption. If you are doing this on a development board where the efuse key is not read-protected, you can extract the key via software. If it is read-protected (production mode), you must use the ESP32's internal decryption engine via the UART ROM bootloader.

Pin Mapping for External UART

If you are bypassing the onboard USB bridge, wire your CP2102 adapter to the ESP32-WROOM-32E as follows:

Automated Dump and Decrypt Script

Below is a complete, compilable Python script that handles the dump and decryption process. It targets the ESP32-WROOM-32E, handles the bootloader strapping sequence, and includes robust error handling for common UART timeouts.

#!/usr/bin/env python3
"""
ESP32 Flash Dump and Decrypt Utility
Targets: ESP32-WROOM-32E (DevKitC V4)
Requires: esptool.py and espsecure.py in system PATH
"""

import subprocess
import sys
import os

# Configuration
PORT = "/dev/ttyUSB0"  # Change to COM3 on Windows
BAUD = 921600
FLASH_SIZE = "4MB"
OUTPUT_ENCRYPTED = "flash_dump_encrypted.bin"
OUTPUT_DECRYPTED = "flash_dump_decrypted.bin"

def run_command(cmd, description):
    print(f"\n[>] {description}...")
    print(f"    Command: {' '.join(cmd)}")
    try:
        result = subprocess.run(
            cmd, 
            check=True, 
            capture_output=True, 
            text=True,
            timeout=120
        )
        print(result.stdout)
        return True
    except subprocess.CalledProcessError as e:
        print(f"[!] Error during {description}: {e.stderr}")
        return False
    except subprocess.TimeoutExpired:
        print(f"[!] Timeout during {description}. Check physical connections.")
        return False

def main():
    # Step 1: Dump the encrypted flash
    dump_cmd = [
        "esptool.py", "--chip", "esp32", 
        "--port", PORT, "--baud", str(BAUD),
        "--before", "default_reset", "--after", "no_reset",
        "read_flash", "0x00000", FLASH_SIZE, OUTPUT_ENCRYPTED
    ]
    
    if not run_command(dump_cmd, "Dumping encrypted flash to file"):
        sys.exit(1)

    # Step 2: Extract the efuse AES key (Only works if efuse is NOT read-protected)
    key_file = "efuse_key.bin"
    key_cmd = [
        "espefuse.py", "--port", PORT, 
        "dump", "--format", "json"
    ]
    # Note: In a real scenario, you'd parse the JSON for the flash_encryption key.
    # For this script, we assume the key is manually extracted to 'efuse_key.bin'
    # or we use the hardware decryption fallback below.

    # Step 3: Decrypt the binary code using espsecure
    # This requires the 256-bit AES key extracted from the efuse block
    if not os.path.exists(key_file):
        print("[!] Efuse key file missing. Cannot decrypt locally.")
        print("    If efuse is read-protected, you must use the ROM bootloader")
        print("    decryption method via 'esptool.py read_flash' with the")
        print("    '--encrypt' flag reversed, or re-flash a debug stub.")
        sys.exit(1)

    decrypt_cmd = [
        "espsecure.py", "decrypt_flash_data",
        "--keyfile", key_file,
        "--address", "0x00000",
        "--output", OUTPUT_DECRYPTED,
        OUTPUT_ENCRYPTED
    ]

    if run_command(decrypt_cmd, "Decrypting binary code"):
        print(f"\n[+] Success! Decrypted binary code saved to {OUTPUT_DECRYPTED}")
    else:
        print("\n[-] Failed to decrypt binary code. Verify your AES key.")
        sys.exit(1)

if __name__ == "__main__":
    main()

Troubleshooting: Exact Error Strings and Ranked Causes

When working with hardware encryption, the margin for error is zero. If your script fails, here are the first three things to check:

1. Boot Strapping Pin State: Ensure GPIO0 is pulled LOW during the exact moment the EN (Reset) pin goes HIGH. If the timing is off by more than 50ms, the chip boots into normal execution mode instead of the UART ROM bootloader, and flash reads will fail.
2. Power Delivery Brownouts: Monitor the 3.3V rail with an oscilloscope. A voltage droop below 3.1V during the high-speed SPI read will corrupt the packet header.
3. Efuse Read Protection: If the FLASH_CRYPT_CNT or key block is read-protected, software extraction of the AES key is physically blocked by the silicon. You cannot decrypt it on your PC; you must rely on the chip's internal decryption engine.

Common Error Strings

For deeper architectural details on how the ESP32 handles these keys in silicon, refer to the official Espressif Flash Encryption Documentation. The esptool.py GitHub repository also maintains an active issue tracker where edge cases regarding specific flash chip vendors (like Winbond vs. GigaDevice) are documented.

Extending and Simplifying the Build

Depending on your workflow, you might want to streamline this process or scale it up for a production testing environment.

How to Simplify the Build

If you are actively developing and just need to read a specific partition (like the ota_0 app partition) rather than the entire 4MB flash, use the ESP-IDF's built-in wrapper. Instead of the Python script above, simply run:

idf.py encrypted-read-flash --port /dev/ttyUSB0 --baud 921600

This command automatically handles the bootloader strapping, reads the efuse key internally via the ROM bootloader, and outputs the decrypted binary code directly to your terminal or file, bypassing the need to manually extract the AES key.

How to Extend the Build

To extend this into a Hardware-in-the-Loop (HIL) testing rig, replace the manual CP2102 adapter with a Raspberry Pi 4 Model B acting as the host. Wire the Pi's hardware UART (GPIO 14/15) to the ESP32, and use the Pi's GPIO pins to physically toggle the ESP32's EN and GPIO0 pins via a Python RPi.GPIO script. This allows you to fully automate the power-cycle, boot-strapping, dumping, and decrypting sequence without human intervention, which is critical for analyzing field-return failures at scale.

Frequently Asked Questions

Can I decrypt binary code from an ESP32 without the original AES key?

No. The AES-256 key is generated by the ESP32's internal hardware random number generator during the first boot after encryption is enabled. It is burned into the efuse block. If you do not have this exact key, and the chip's internal decryption engine is disabled or the chip is dead, the binary code is cryptographically secure and cannot be decrypted on a PC.

How do I decrypt binary code if the efuse key block is read-protected?

If the efuse key block is read-protected (which is standard for production firmware), software tools like espefuse.py cannot read the key. However, the ESP32's ROM bootloader can still access it internally. You must use the esptool.py read_flash command with the --encrypt flag omitted, or use idf.py encrypted-read-flash, which commands the ROM bootloader to decrypt the data on the fly and send the plaintext over UART.

Is it possible to decrypt binary code from an ESP32-S3 or ESP32-C3 using the same method?

The fundamental concept is the same, but the toolchain flags differ. The ESP32-S3 and ESP32-C3 use different flash encryption schemes and efuse layouts (e.g., the S3 supports XTS-AES-128/256). You must change the --chip argument in esptool.py to esp32s3 or esp32c3, and ensure your ESP-IDF version is v4.4 or higher, as older versions lack the correct decryption algorithms for the newer silicon variants.