SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsesp32-secureboot

esp32-secureboot

Security & auditing

View repository

Updated 10-15 21:48

About this skill

ESP32 Secure Boot v2 and Flash Encryption

Every step of secure boot and encryption touches eFuse—one-time, irreversible. The principles of this Skill: rehearse first, burn later; key governance before technical implementation; facts not captured by the baseline (such as ED25519)are forbidden to write。

Determine Task Type

  1. Enabling the security scheme before mass production: the enabling order and rehearsal of SB v2 + Flash Encryption → Workflow (decision-oriented main path).
  2. Key governance: how signing keys are generated, where they are stored, how CI uses them → key-governance(requests like "commit the key into git" are directly refused).
  3. Technical fact verification: SBv2 algorithms/eFuse behavior/FE count limits → sb2-facts。
  4. Combination with OTA: the upgrade channel under signed app + encrypted flash → see "Relationship with OTA", implementation details routed to esp32-ota。

Prerequisites / Preflight

idf.py --version
  1. Chip model + revision: the classic ESP32 requires rev 3.0+ to support SBv2 (baseline high confidence); the official page for C3 describes RSA-3072. If the model is unknown, stop first.
  2. Whether OTA already exists: in FE Release mode, new images can only enter the device via OTA—enabling Release encryption without an OTA channel = cutting off your own retreat.
  3. Availability of flashing/efuse tools: for specific flashing commands and toolchains (espsecure, etc.), refer to the official security documentation (verified at runtime); this Skill does not give parameters from memory.
  4. Current state of keys: are there existing signing keys? In whose hands? Have they ever been committed to git? (If so = treat as leaked, see key-governance.)

Offline Baseline

  • ESP-IDF baseline = v6.1(as of the walkthrough 2026-09-02, not automatically updated); SBv2/FE facts are cited from baseline §6 (official secure-boot-v2 and flash-encryption documentation, high confidence).
  • Attribution of the ED25519 Secure Boot scheme: UNVERIFIED—this Skill and its downstream must never write it。
  • The attribution of ECDSA SBv2 is medium confidence: it may only be stated as "exists on some chips; v6.1 disables ECDSA SBV2 for H2/C5/P4 due to a vulnerability"; for details see sb2-facts。
  • Minimum IDF version per chip: UNVERIFIED, do not hard-code.

Contracts (device contracts)

  1. eFuse is one-time: burning/write protection/revocation are irreversible; before any "burn" action, the target and consequences must be restated and confirmed.
  2. After the public key digest is written into eFuse: write protection must be enabled, butread protection must not be(software verification needs to read the digest; mistakenly enabling read protection will make boot impossible, baseline high confidence).
  3. Private keys never enter the device: signing happens on the host side; the device only holds the public key digest.
  4. FE keys are not readable back: the key is stored in eFuse block1; after burning, write + read protection is applied, and software cannot read it back.
  5. Anti-hallucination red line: efuse block numbers, KEY_PURPOSE values, etc. may only cite sb2-facts entries annotated with confidence; do not fabricate the rest.

Secure Boot v2 key points (baseline high-confidence excerpts)

  • Signing scheme: ESP32 (rev 3.0+) and ESP32-C3 official pages describe RSA-3072（RSA-PSS）。
  • Public key SHA-256 digest burned into eFuse（ESP32: BLK2；C3: BLOCK_KEY0-5 + KEY_PURPOSE=SECURE_BOOT_DIGESTX）。
  • Digest slots: ESP32 has only 1; C3 has up to 3 (KEY_REVOKEX revocation,irreversible, supports conservative/aggressive revocation strategies).
  • Complete fact table with confidence annotations → sb2-facts。

Flash Encryption key points (high-confidence baseline excerpt)

  • AES-256 (hardware engine); key stored in eFuse block1, write- and read-protected after burning, not readable back by software.
  • Development mode: plaintext serial flashing ≤ 3 times(FLASH_CRYPT_CNT counter)—during development, you should be aware of the pacing before the 3rd time.
  • Release mode: after burning the protection bit, plaintext flashing is no longer possible, new images can only go through OTA—before enabling, confirm the OTA channel is available (→ esp32-ota）。

Relationship with OTA

  • Combined goals:signed app + encrypted flash—SB prevents tampering/image swapping, FE prevents reading flash to obtain firmware and keys.
  • In FE Release mode, OTA is the only upgrade channel; OTA images must be signed images, anti-rollback requirement (secure_version into eFuse, can only increment) is assessed in this skill, implemented in esp32-ota。
  • Enabling order: SB first, then FE (annotated as the officially recommended order;specific steps are subject to the official security documentation, verify at runtime before citing—this baseline did not capture the order items one by one).
  • Upgrade link security (HTTPS, etc.) is the responsibility of esp32-ota , this skill does not duplicate it.

Capability Boundaries + Hand-off

User Intent Skill
Signing key in git/CI plaintext refusal: reject and provide governance plan (Workflow step 4 + key-governance)
OTA rollback switch/upgrade implementation esp32-ota
Release naming/checksums/artifact gating (key governance integration) fw-release-gate
Real-device verification of secure boot behavior fw-hil-testing
Unable to boot/crash after enabling esp32-debug(serial log + coredump)
Upgrade troubleshooting for abnormal encrypted images esp32-ota

Out of scope: TPM/trusted execution solution design, cloud KMS integration implementation—only point to official documentation, do not elaborate.

Workflow (enable before mass production: rehearse first, then burn)

  1. Decide the plan: verify SBv2 support and algorithms per chip (sb2-facts); decide SB only / SB + FE combination; FE Release prerequisite = OTA channel ready.
  2. Development-phase rehearsal (mandatory): inwithout burning production eFuses run through the entire process under the premise—key generation, signing, development mode FE (≤3 plaintext flashing discipline), OTA signed image upgrade, failure rollback; keep rehearsal conclusions on record.
  3. Key governance in place (gate before burning): per key-governance complete—generation/offline storage/access records;production private key never enters the repository or CI in plaintext; revocation plan (C3 slot and KEY_REVOKEX irreversible) written clearly.
  4. Production burning: on the production line, burn eFuses according to the official security documentation process (command parameters verified at runtime); first do a small-batch trial production to verify boot, OTA, upgrade failure rollback, then scale up.
  5. Acceptance: Validation Gates all pass; real-device evidence → fw-hil-testing; artifact and checksum gating → fw-release-gate。

Validation Gates

  1. Rehearsal records: signing process, FE development mode flashing count ledger, OTA signed image upgrade success—all documented and verifiable.
  2. Tampering experiment (real device): flash a modified image → device refuses to boot (evidence SB is in effect).
  3. Read-protection red-line recheck: public key digest eFuse is write-protected only, not read-protected, and the device can boot normally.
  4. Small-batch trial production: ≥3 devices complete flashing + OTA upgrade + power-loss rollback, documented (no real hardware = Pending HIL).
  5. Governance audit: confirm production private keys exist only in the agreed custody locations, and that git history/CI logs contain no keys (including historical commits).

Pitfalls

  1. Do notcommit the secure boot private key into git or put it in a CI plaintext variable—"convenient for CI" is not a reason; after a leak, the only way to stop the bleeding is irreversible slot revocation.
  2. Do notskip rehearsal and burn eFuses directly on production devices—a one-time burn mistake (wrong block/accidentally enabling read protection) cannot be undone.
  3. Do notenable eFuse read protection for the public key digest—software verification needs to read it, and reading it will prevent boot.
  4. Do notenable FE Release mode before the OTA channel is established—afterward, new images can only get in via OTA.
  5. Do notwrite ED25519-related scheme attribution—UNVERIFIED; for algorithm questions, only cite entries already marked in sb2-facts.
  6. Do nottreat the FE development mode's "3 plaintext burns" as an unlimited quota to spend on trial and error—save the last burns for verification that truly needs them.
  7. Do notassume all chips have identical SBv2 details (slot count and block layout differ)—check sb2-facts for the target chip.

Official Sources

Privacy

Signing keys, eFuse configuration, and device security state are at the highest sensitivity level: this Skill does not collect, store, or send any key material externally; all examples use placeholders only; if a user pastes a key fragment, prompt them to rotate it immediately and handle it per the leak process (key-governance §5).