CipherFuse logo
CipherFuse Wiki  ·  v4.1

How to encrypt ESP32 firmware

CipherFuse walkthrough for flash encryption: export the binaries, prove the board boots, save the key, then burn it. Download CipherFuse for Windows or Ubuntu.

Why your ESP32 firmware needs to be secured

The ESP32 is one of the most widely deployed microcontrollers in the world. It powers commercial IoT devices, industrial sensors, smart home products, agricultural monitors, access control systems, and medical instruments. In almost every one of those applications, the firmware is the product — it embodies years of engineering work, proprietary algorithms, calibration data, and business logic that took real money and time to build.

By default, every ESP32 ships with its flash storage completely unprotected. Any person with a USB cable and a free tool can dump the entire firmware from your device in under a minute — including your Wi-Fi credentials, API keys, encryption secrets, and every line of code you wrote. That dumped binary can be loaded onto a blank chip and cloned at will. Competitors have done exactly this. Contract manufacturers have done it. Devices returned under warranty have had their firmware extracted and resold.

How flash encryption works

Flash encryption closes that door. CipherFuse creates a key on your computer and burns it into eFuse memory — a region of the chip that can be written once. After the burn, the key cannot be read back over USB. The chip still uses it internally: every read from flash is decrypted in hardware. The binary sitting on the flash chip is meaningless noise to anyone who dumps it, and a cloned flash chip in a different board produces nothing but garbage.

The encryption and decryption happen entirely in hardware, at full bus speed. There is no firmware overhead and no performance penalty for using it.

Secure Boot

Secure Boot is a separate Espressif feature. It checks a signature on the firmware before the chip runs it, so a board will refuse an image you did not sign. Flash encryption and Secure Boot solve different problems: encryption hides the bytes in flash, Secure Boot refuses firmware you did not author.

CipherFuse enables flash encryption. It does not burn Secure Boot keys or sign images. Use it when you need the firmware unreadable if someone dumps the flash.

Burning the flash-encryption key is irreversible. There is no factory reset. CipherFuse asks you to confirm before it burns eFuses. Keep the key file. Without that file you cannot encrypt a later update for the same board.

Doing this by hand means coordinating esptool, espefuse, and espsecure, with a different key block and bootloader address on each chip. CipherFuse bundles those tools and walks the steps in order: prove the firmware boots, save a key, then encrypt.

Supported chips

On the Operations tab, set Target Chip to the same board you compiled for. That choice sets the bootloader address and the encryption scheme. The other three files stay at the same addresses on every chip.

Chip            Bootloader    Scheme
ESP32           0x1000        AES-256
ESP32-S2        0x1000        XTS-AES
ESP32-S3        0x0           XTS-AES
ESP32-C2        0x0           XTS-AES
ESP32-C3        0x0           XTS-AES
ESP32-C6        0x0           XTS-AES
ESP32-H2        0x0           XTS-AES
ESP32-P4        0x2000        XTS-AES

Partition       0x8000
boot_app0       0xE000
Application     0x10000

Boards with a native USB port (S2, S3, C3, C6, H2, P4) should stay at flash baud 115200. Raising the baud makes the USB device disappear mid-flash. A CP2102 or CH340 UART board can use a higher baud.

Prerequisites

You do not install esptool yourself. The Windows zip already contains Python, the window toolkit, and the Espressif tools. On Ubuntu, install.sh installs them. The links below are only so you can read the upstream licences.

Windows package

Unzip CipherFuse-4.1-windows.zip and run CipherFuse.exe. Already inside that folder:

Ubuntu installer

Unpack the tarball, then run ./install.sh. That script uses apt for Python and PyQt6, then installs the esptool libraries from the wheels in the package. Ubuntu 22.04 and 24.04 on 64-bit PC hardware are the tested targets.

USB-UART drivers

Most ESP32 dev boards use one of two USB-UART bridge chips. Native-USB boards (ESP32-S2, S3, C3) appear automatically on Windows 10+ and Ubuntu 22+ with no extra driver. For classic UART bridge boards:

Encryption walkthrough

Follow these steps in order. Only the last step burns eFuses. That step is marked irreversible and CipherFuse asks you to confirm before it runs.

  • 1
    Build and export the four firmware files

    CipherFuse flashes compiled .bin files. A normal Arduino or ESP-IDF app needs four of them, each on its own row of the Firmware tab.

    Arduino IDE

    Select the board under Tools → Board, then Sketch → Export Compiled Binary (Ctrl + Alt + S). That export writes three files. The names look like this:

    • YourSketch.ino.bootloader.bin — bootloader row
    • YourSketch.ino.partitions.bin — partition row, address 0x8000
    • YourSketch.ino.bin — application row, address 0x10000

    Export does not write boot_app0.bin. That file is the OTA slot selector and it ships with the Arduino ESP32 core, usually at:

    %LOCALAPPDATA%\Arduino15\packages\esp32\hardware\esp32\<version>\tools\partitions\boot_app0.bin

    On the Firmware tab, click Scan Arduino Build Folder and choose the folder that contains the exported bins. The scan fills the bootloader, partition, and app rows, and it also finds boot_app0.bin in the Arduino package. Put that file on the boot_app0 row (0xE000).

    If boot_app0.bin is missing, the flash can succeed and the app still never starts. Erased OTA data is all 0xFF, and the bootloader cannot choose an app slot.

    ESP-IDF

    Run idf.py build. From the build/ folder, use the bootloader image, partition-table.bin, your application .bin, and ota_data_initial.bin on the boot_app0 row when the partition table has an otadata partition.

    The flash address comes from the row you drop the file into, not from the filename. The chip you select on the Operations tab sets the bootloader address. Match it to the board you compiled for.

  • 2
    Connect your board and select the port

    Plug the board in with a data cable. On the Operations tab, set Target Chip, then open Serial Port. The list shows only ports that are actually present. If it is empty, click Refresh after the cable is seated.

    Click Read Chip Info. A chip description in the log means the port is the right one. Close the Arduino Serial Monitor, PuTTY, and any other program that has that port open before you flash.

    On a native USB board, leave Settings → Flash baud at 115200. A higher baud drops the port with “Cannot configure port”. UART-bridge boards (CP2102, CH340) can use a faster baud.

    If no port appears, try another cable, install the bridge-chip driver from the list above, or hold BOOT, tap RESET, release BOOT, and refresh.

  • 3
    Flash plaintext and confirm the board runs

    Open the Firmware tab and check that all four rows have a file. Click Flash Plaintext (Test). This writes the bins with no encryption and does not burn eFuses.

    Unplug nothing until the log says the flash finished. Then confirm the sketch actually runs: serial output, an LED, a relay, whatever your firmware is supposed to do. If it does not run now, encrypting it will not fix that.

  • 4
    Generate an encryption key and back it up

    Back on Operations, the Key File box defaults to:

    Documents\CipherFuse\flash_encryption_key.bin

    Click Generate New Key. That writes a file on your computer. It does not touch the chip. If you browse to a folder instead of a .bin file, CipherFuse saves flash_encryption_key.bin inside that folder.

    Copy that .bin somewhere else before you continue: another disk, a password store, a second machine. The chip will not let you read the key back later. Lose the file and you cannot build an encrypted update for that board.

  • 5
    Flash and encrypt irreversible

    On the Firmware tab, click Flash & Encrypt. CipherFuse burns the key into eFuse if the chip does not already have one, then sends the four plaintext bins. The chip encrypts each block as it is written. Read the confirmation dialog before you accept it.

    When the log finishes, the board reboots on encrypted firmware. Later updates for that same board must use the same key file. Generate a new key only for a new, still-unlocked board.

    Leave Disable UART download mode and Disable JTAG unchecked on the Settings tab unless you intend to close those doors permanently. After UART download is disabled, you cannot recover the board from this tool.

    Encrypt Offline writes .enc.bin copies on your PC. Flash .enc.bin sends those copies. The button most people want is Flash & Encrypt.

If something goes wrong

Permission denied while generating a key

The key path is a folder, or it sits somewhere Windows will not let the app write, such as Program Files. Point Key File at a .bin file under Documents, or pick a folder you own. CipherFuse appends flash_encryption_key.bin when the path is a folder.

The flash succeeds and the app never starts

The usual causes are a missing boot_app0.bin on the 0xE000 row, or the wrong Target Chip (the bootloader then lands at the wrong address). Fix the files, flash plaintext again, and confirm the app runs before you encrypt.

Cannot configure port

Native USB dropped the COM port because the baud changed. Set flash baud to 115200, unplug and replug, refresh the port list, and retry.

The port is busy, or the burn looks stuck

Close anything else using the COM port, then refresh. A key burn no longer waits for you to type BURN. If it still fails, hold BOOT, tap RESET, release BOOT, and run it again.