esptool write-flash should --encrypt when CONFIG_SECURE_FLASH_ENC_ENABLED

[rtyle]

Component name

esp32

Link to component documentation on our website

https://esphome.io/components/esp32/

Describe the enhancement

I have secrets that my device needs to know at runtime. I would like these secrets to be protected, at rest, with flash encryption.

https://docs.espressif.com/projects/esp-idf/en/stable/esp32/security/flash-encryption.html

An esphome esp32 component with a framework of esp-idf and sdkconfig_options that include CONFIG_SECURE_FLASH_ENCRYPTION_AES256: "y" is what a project needs for encrypted flash.

esphome run project.yaml will properly use esptool to write-flash, and reset the device over USB.
The flash will have been written unencrypted.
The second stage bootloader will

• burn eFuses with random private keys for encryption and decryption
• encrypt flash, including itself, with these keys
• burn an eFuse to tell the first stage bootloader to expect (and decrypt) the encrypted flash.

Unfortunately, any subsequent esphome run project.yaml (or esphome upload project.yaml) will fail as it will result in unencrypted images being written to flash when the first stage bootloader expects encrypted images.
The first stage bootloader will go into an infinite loop complaining forever - something like

 invalid header: 0x487325b7

The project can be resurrected by flashing the whole firmware.factory.bin image with the --encrypt option.

python -m esptool --chip esp32s3 --port /dev/ttyACM0 write-flash --encrypt 0x0 .esphome/build/project/.pioenvs/project/firmware.factory.bin

Which version of ESPHome has the issue?

2025.11.0-dev

What type of installation are you using?

pip

What platform are you using?

ESP32

Component causing the issue

esp32 esp-idf

YAML Config

---

esphome:
  name: project

esp32:
  board: m5stack-cores3
  cpu_frequency: 240Mhz
  framework:
    type: esp-idf
    sdkconfig_options:
      CONFIG_PARTITION_TABLE_OFFSET: "0xf000"
      CONFIG_SECURE_FLASH_ENC_ENABLED: "y"
      CONFIG_SECURE_FLASH_ENCRYPTION_AES256: "y"
      CONFIG_NVS_ENCRYPTION: "n"
      CONFIG_NVS_SEC_KEY_PROTECT_USING_FLASH_ENC: "n"
  partitions: partitions.csv
  flash_size: 16MB

Anything in the logs that might be useful for us?

partitions.csv

app0,		app,	ota_0,	0x10000,	0x700000,
app1,		app,	ota_1,	,	0x700000,
otadata,	data,	ota,	,	0x2000,
phy_init,	data,	phy,	,	0x1000,
nvs,		data,	nvs,	,	0x6D000,

---

esphome run project.yaml
INFO ESPHome 2025.11.0-dev
INFO Reading configuration project.yaml...
INFO Generating C++ source...
INFO Compiling app...
Processing project (board: m5stack-cores3; framework: espidf; platform: https://github.com/pioarduino/platform-espressif32/releases/download/54.03.21-2/platform-espressif32.zip)
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
INFO Package configuration completed successfully
INFO Package configuration completed successfully
HARDWARE: ESP32S3 240MHz, 320KB RAM, 16MB Flash
 - framework-espidf @ 3.50402.0 (5.4.2) 
 - tool-cmake @ 3.30.2 
 - tool-esp-rom-elfs @ 2024.10.11 
 - tool-esptoolpy @ 5.0.2 
 - tool-mklittlefs @ 3.2.0 
 - tool-ninja @ 1.13.1 
 - tool-scons @ 4.40801.0 (4.8.1) 
 - toolchain-xtensa-esp-elf @ 14.2.0+20241119
Reading CMake configuration...
No dependencies
RAM:   [          ]   4.1% (used 13556 bytes from 327680 bytes)
Flash: [          ]   3.1% (used 230246 bytes from 7340032 bytes)
======================================================================== [SUCCESS] Took 2.20 seconds ========================================================================
INFO Successfully compiled program.
esptool v5.1.0
Connected to ESP32-S3 on /dev/ttyACM0:
Chip type:          ESP32-S3 (QFN56) (revision v0.2)
Features:           Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz
Crystal frequency:  40MHz
USB mode:           USB-Serial/JTAG
MAC:                30:ed:a0:0a:f9:94

Stub flasher running.
Changing baud rate to 460800...
Changed.

Configuring flash size...
Auto-detected flash size: 16MB
Flash will be erased from 0x00010000 to 0x00048fff...
Flash will be erased from 0x00000000 to 0x00007fff...
Flash will be erased from 0x0000f000 to 0x0000ffff...
Flash will be erased from 0x00e10000 to 0x00e11fff...
Wrote 230640 bytes (126970 compressed) at 0x00010000 in 1.3 seconds (1387.7 kbit/s).
Hash of data verified.
SHA digest in image updated.
Wrote 31504 bytes (19472 compressed) at 0x00000000 in 0.3 seconds (748.5 kbit/s).
Hash of data verified.
Wrote 3072 bytes (130 compressed) at 0x0000f000 in 0.0 seconds (942.9 kbit/s).
Hash of data verified.
Wrote 8192 bytes (31 compressed) at 0x00e10000 in 0.0 seconds (1388.5 kbit/s).
Hash of data verified.

---

picocom /dev/ttyACM0 

invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
invalid header: 0xec5fdb2c
...

---

python -m esptool --chip esp32s3 --port /dev/ttyACM0 write-flash --encrypt 0x0 .esphome/build/project/.pioenvs/project/firmware.factory.bin

esptool v5.1.0
Connected to ESP32-S3 on /dev/ttyACM0:
Chip type:          ESP32-S3 (QFN56) (revision v0.2)
Features:           Wi-Fi, BT 5 (LE), Dual Core + LP Core, 240MHz
Crystal frequency:  40MHz
USB mode:           USB-Serial/JTAG
MAC:                30:ed:a0:0a:f9:94

Stub flasher running.

Configuring flash size...
Flash will be erased from 0x00000000 to 0x00e11fff...


Warning: Compress and encrypt options are mutually exclusive.
Will flash '.esphome/build/project/.pioenvs/project/firmware.factory.bin' uncompressed.
Wrote 14761984 bytes at 0x00000000 in 85.6 seconds (1379.6 kbit/s).
Cannot verify written data if encrypted or in secure download mode.

Hard resetting via RTS pin...

---

picocom /dev/ttyACM0
<nothing, as expected>

Additional information

I made the following change in my esphome fork to fix the problem that I am having right now.
Unfortunately, this change would perform an --encrypt write-flash on the very first flash.
Hopefully, this would be ignored on a device that is not yet set up for encryption but I do not know.
I am already past that point with my device.

git diff esphome/__main__.py
diff --git a/esphome/__main__.py b/esphome/__main__.py
index b0f541f52..1b050f35b 100644
--- a/esphome/__main__.py
+++ b/esphome/__main__.py
@@ -456,6 +456,8 @@ def upload_using_esptool(
             "--flash-size",
             "detect",
         ]
+        if "y" == CORE.config.get("esp32", {}).get("framework", {}).get("sdkconfig_options", {}).get("CONFIG_SECURE_FLASH_ENC_ENABLED", None):
+            cmd.append("--encrypt")
         for img in flash_images:
             cmd += [img.offset, str(img.path)]

Use cases

I have developed an SMTP component that can send email through smtp.gmail.com.
To do so requires creating a Google account with an application password and sharing that with my esphome device.
Even though I created a dedicated Google account for this purpose, I want to protect the account credentials written to flash by encryption.

Anything else?

No response

[github-actions[bot]]

🏷️ I've automatically added the component: esp32 label to help categorize this feature request.