Protect your product

The problem

By default an ESP32 board is fully readable. Anyone who connects it can dump the flash and read your baked PHP source and your .env values in plaintext:

esptool read_flash 0 0x400000 dump.bin
strings dump.bin | grep -i secret     # finds your .env values, your PHP, ...

Two hardware features close this:

• Flash Encryption — a key in eFuse (read-protected, never leaves the chip) encrypts the flash. A dump is noise, and reflashing it onto another chip is useless.
• Secure Boot v2 — only firmware signed with your offline private key boots.

What gets protected

Flash Encryption covers the firmware image automatically; a data partition is only covered when it is flagged encrypted, which the secure flag does for the baked PHP source.

So secure = true protects the baked PHP source and the .env: the .env is already inside the auto-encrypted app, and the flag adds the encrypted flag the PHP-source partition needs. For a protected product keep the source embedded, not on microSD.

The two features side by side

They solve different problems and you usually want both. Neither can be undone.

Both together = a product whose flash is unreadable and which runs only your firmware. Both burns are permanent, so provision on units meant for it. The one irreplaceable secret is the Secure Boot signing key: back up every deploys/<MAC>.pem offline — losing it ends updates for that board.

Step 1 — Flash Encryption (the secure flag)

Turn it on in php-esp32.config.toml:

secure = true

A secure build does two things:

• marks the embedded storage partition encrypted — data partitions aren't encrypted by default, so without this the baked PHP source would stay in plaintext even with Flash Encryption on;
• enables Flash Encryption in development mode in the firmware's sdkconfig.

The .env needs nothing extra: it is compiled into the app image, which is always encrypted.

Build and flash as usual:

phpflash build --clean
phpflash flash

On the first boot the bootloader generates the encryption key, burns it into eFuse, and encrypts the flash in place. From then on the contents are unreadable from outside.

Step 2 — Verify it worked

Dump the flash again and confirm your secrets are now noise, not text:

esptool read_flash 0 0x400000 dump.bin
strings dump.bin | grep -i secret     # now finds nothing — the data is encrypted

Compare against a dump of the same firmware built without secure = true: there the string is plainly visible.

phpflash discover also reads the chip's eFuses and reports the protection state directly:

Flash encryption: enabled
Secure boot:      enabled

Step 3 — Secure Boot v2

Flash Encryption stops reading; Secure Boot stops running unsigned firmware. Turn it on with a second flag:

secure = true
secure_boot = true
# secure_boot_keys_dir = "./deploys"   # where <MAC>.pem lives (default: ./deploys)

The convention is one signing key per unit, stored as deploys/<MAC>.pem — a private secret you keep offline. phpflash build provisions it for you: with the board connected it reads the MAC, generates deploys/<MAC>.pem (RSA-3072, kept private at mode 600) the first time, then signs the bootloader and app with it. An existing key is reused (so later builds don't touch the board). To pre-provision a key without the board, run phpflash secure-key --mac 28:84:85:67:57:80.

On first boot the chip burns the public-key digest into eFuse, and from then on only images signed with your key boot. (Secure Boot moves the partition table to 0xc000 to fit the signed bootloader, so the flash offsets change — flash with phpflash flash.)

Development vs Release mode

• Development mode (what secure = true sets): the chip is encrypted, but the serial download path still works so you can keep flashing. Use it to validate the whole flow.
• Release mode: one-way. The plaintext serial download path is disabled and the encryption settings are locked. This is the production setting — set CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y and burn the units you ship, once you're confident.

Key model

• Per-device key, generated on-chip (the development-mode default): strongest, every unit is unique, but you can't pre-build one encrypted image for all units.
• Shared, pre-generated key: lets you flash one encrypted image across a production run (generate with espsecure.py generate_flash_encryption_key), at the cost of a single key for the whole fleet.

For anti-cloning, prefer per-device.

What is not covered

• store_* (the persistent store) lives in an NVS partition, which Flash Encryption does not cover. Secrets written there at runtime need separate NVS Encryption (a dedicated nvs_keys partition) — not set up by the secure flag.
• PHP source on a microSD card is never protected — the card is external and plaintext. For a protected product, bake the source into the (encrypted) firmware (storage_type = "embedded"), not on SD.

Hardware note

For the strongest Secure Boot, use an ESP32 ECO3 or a modern ESP32-S3 / C-series chip. A brand-new chip is almost always fine; only very old stock may predate the needed revision.

Commands: before vs after

The commands don't change — it's the same phpflash build and phpflash flash throughout. The flags steer what each one does; phpflash adapts (provisioning the key, signing, and switching to encrypted flashing) on its own.

What phpflash does under the hood so you don't have to:

• Build: with secure it marks the storage partition encrypted; with secure_boot it provisions deploys/<MAC>.pem, signs the bootloader and app, and shifts the partition table (so the flash offsets move — which is exactly why you let the tool handle flashing).
• Flash: on a virgin chip it writes plaintext (the chip encrypts itself on first boot); once the chip is encrypted it detects that and runs encrypted-flash, so the images go in through the chip's own hardware encryption. You never type an esptool --encrypt line or chase offsets by hand.