Secure Boot Implementation in ESP-IDF

Leave a Comment / By /

Chapter 235: Secure Boot Implementation in ESP-IDF

Chapter Objectives

By the end of this chapter, you will be able to:

  • Understand the concept of a “root of trust” and its importance in device security.
  • Explain the cryptographic process behind Secure Boot, including digital signatures.
  • Generate a secure private/public key pair for signing firmware.
  • Enable and configure Secure Boot V2 on an ESP32 device.
  • Securely update firmware on a device with Secure Boot enabled.
  • Distinguish between Flash Encryption and Secure Boot and understand how they complement each other.

Introduction

In the previous chapter, we secured our firmware’s confidentiality with Flash Encryption, making it unreadable to unauthorized parties. However, a critical question remains: how do we ensure the firmware running on the device is authentic and hasn’t been maliciously replaced? An attacker could still wipe the flash, place their own (potentially encrypted) malicious firmware on it, and take control of the device.

This is where Secure Boot comes in. It is a security feature that guarantees the integrity and authenticity of your application code. It creates an unbroken chain of trust starting from the hardware itself, ensuring that the ESP32 will only execute software that has been digitally signed by a trusted developer (you!). When combined with Flash Encryption, Secure Boot provides a robust, layered defense, protecting your device against both intellectual property theft and malicious code execution.

Theory

Secure Boot establishes a hardware root of trust. This means the verification process is anchored in the physical silicon of the chip, using one-time-programmable eFuses that cannot be altered once programmed. ESP-IDF uses a system called Secure Boot V2, which is based on RSA-3072 public-key cryptography.

The Core Concept: Digital Signatures

Imagine you are sending a critical executive order. To prove it genuinely came from you, you sign it with your unique, personal signature. Anyone can compare that signature to a public record of your signature to verify its authenticity.

Digital signatures work on a similar principle, using a private key and a public key.

  1. Private Key: This key is kept absolutely secret by the developer. It is used to “sign” the firmware image. The signing process involves creating a cryptographic hash (a unique, fixed-size fingerprint, specifically SHA-256) of the firmware and then encrypting that hash with the private key. This encrypted hash is the digital signature, which is then appended to the firmware binary.
  2. Public Key: This key is mathematically linked to the private key but cannot be used to deduce it. The public key is placed on the ESP32 device. Its purpose is to “verify” a signature. The bootloader uses the public key to decrypt the signature attached to the firmware, revealing the original hash. It then calculates its own SHA-256 hash of the received firmware. If the two hashes match, the signature is valid, and the firmware is proven to be authentic.
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
graph TB
    subgraph "Developer PC (Offline Signing)"
        direction LR
        A[Firmware Binary] --> B{SHA-256<br>Hash};
        C(<b>Private Key</b><br><i>Kept Secret</i>) -- "Encrypts Hash" --> D[Digital Signature];
        B --> D;
        A --> E((Signed Firmware));
        D -- "Append Signature" --> E;
    end

    subgraph "ESP32 Device (On-Boot Verification)"
        direction LR
        F((Signed Firmware<br>from Flash)) --> G{Separate Firmware<br>& Signature};
        G -- "Firmware" --> H{SHA-256<br>Hash};
        G -- "Signature" --> I{Decrypt with<br>Public Key};
        J(<b>Public Key</b><br><i>Stored on Device,<br>Verified by eFuse</i>) -- "Verifies Signature" --> I;
        I -- "Original Hash" --> K{{Compare<br>Hashes}};
        H -- "Calculated Hash" --> K;
        K -- "Hashes Match?" --> L{Boot};
        L -- "Yes" --> M[Execute<br>Application];
        L -- "No" --> N[Boot Aborted!];
    end

    E -- "Flash to Device" --> F

    %% Styling
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef check fill:#FEE2E2,stroke:#DC2626,stroke-width:1px,color:#991B1B;
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;
    classDef start fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;

    class A,E,F start;
    class B,G,H,I process;
    class C,J,D process;
    class K decision;
    class L decision;
    class M success;
    class N check;

Anchoring Trust in Hardware: The Role of eFuses

The entire security model would collapse if an attacker could simply replace the public key on the device with their own. Secure Boot V2 prevents this by permanently storing a digest (a SHA-256 hash) of the public key in the SECURE_BOOT_KEY_DIGEST eFuse block.

The secure boot process works like this on the first boot:

  1. The 2nd stage bootloader is loaded. It contains a copy of the public key.
  2. The bootloader calculates a SHA-256 hash of its embedded public key.
  3. It burns this hash into the SECURE_BOOT_KEY_DIGEST eFuse.
  4. It also burns the ABS_DONE_0 eFuse, which permanently enables Secure Boot. This change is irreversible.

On all subsequent boots:

  1. The bootloader loads the application image from flash.In
  2. It verifies the application’s digital signature using its embedded public key.
  3. Crucially, before trusting the public key for verification, it first calculates a hash of that key and compares it against the hash stored permanently in the eFuse.
  4. If the public key hash doesn’t match the one in the eFuse, or if the application’s signature is invalid, the bootloader will halt and refuse to run the code.

This process ensures that only firmware signed with the original, trusted private key will ever be executed.

Feature Flash Encryption Secure Boot
Primary Goal 🔒Confidentiality 🛡️Authenticity & Integrity
Analogy Putting documents in a locked safe. The contents are hidden. Checking the wax seal and signature on a royal decree. It proves the origin is legitimate and it hasn’t been altered.
Mechanism Symmetric AES encryption. A single, on-chip key both encrypts and decrypts the flash content on-the-fly. Asymmetric RSA digital signatures. A secret private key signs firmware; a public key on the device verifies the signature.
Protects Against IP theft, firmware reverse-engineering, and extraction of sensitive data (credentials, certificates) from the physical flash chip. Running unauthorized or malicious firmware. Prevents an attacker from replacing your code with their own, even if it’s also encrypted.
Hardware Root of Trust The AES key is stored in a write-protected eFuse. A hash of the public key is stored in a write-protected eFuse, anchoring the entire chain of trust.
Overall Role Keeps your software secret. Ensures your software is genuine.
Combined Benefit Maximum Security: You are running genuine, untampered firmware, and that firmware cannot be read or cloned by anyone with physical access.

Flash Encryption vs. Secure Boot: A Quick Analogy

  • Flash Encryption is like putting your documents in a locked safe (confidentiality). Only the correct key (the on-chip key) can open it and see the contents.
  • Secure Boot is like checking the wax seal and signature on a royal decree (authenticity). It doesn’t hide the contents, but it proves the decree is genuine and hasn’t been tampered with.

For maximum security, you use both: you send your authentic, signed decree inside a locked safe.

Practical Example: Enabling Secure Boot

Unlike Flash Encryption, enabling Secure Boot requires a preliminary step: generating your secret signing key.

Step 1: Generate the Secure Boot Signing Key

This key is the root of trust for your products. It must be generated once and kept in a secure location. If you lose this key, you can no longer create updates for devices that trust it.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Open Sans'}}}%%
graph TD
    A["Start: Developer PC"] -- "1- Generate Key<br><b>(esp_secure.py)</b>" --> B["Private Key (.pem)"];
    B -- "<b>CRITICAL:</b><br>Store in Secure<br>Location!" --> C{Project Menuconfig};
    C -- "2- Enable Secure Boot<br>& Provide Key Path" --> D["Save Configuration"];
    D -- "3- Build Project<br><b>(idf.py build)</b>" --> E["Firmware is<br>Automatically Signed"];
    E -- "4- Flash Device<br><b>(idf.py flash)</b>" --> F{Device First Boot};
    
    subgraph "Irreversible eFuse Burn"
        F -- "Detects Secure Boot Flag" --> G["Burns Public Key Hash<br>to eFuse"];
        G -- "Permanently Enables<br>Secure Boot eFuse" --> H((Hardware Root of Trust<br>Established));
    end
    
    H --> I{Subsequent Boots};
    I -- "Bootloader Verifies<br>App Signature" --> J["Application Runs"];

    %% Styling
    classDef start fill:#EDE9FE,stroke:#5B21B6,stroke-width:2px,color:#5B21B6;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:1px,color:#1E40AF;
    classDef decision fill:#FEF3C7,stroke:#D97706,stroke-width:1px,color:#92400E;
    classDef check fill:#FEE2E2,stroke:#DC2626,stroke-width:2px,color:#991B1B;
    classDef success fill:#D1FAE5,stroke:#059669,stroke-width:2px,color:#065F46;

    class A,E start;
    class B,D,G process;
    class C,F,I decision;
    class H,J success;
  1. Open an ESP-IDF terminal in VS Code (ESP-IDF: Open ESP-IDF Terminal).
  2. Create a directory for your secret keys outside of your project folder.
  3. Run the following command to generate the private key file (secure_boot_signing_key.pem):
Bash
esp_secure.py generate_secure_boot_key my_secure_boot_key.pem

Warning: Back up this my_secure_boot_key.pem file in multiple, secure locations (e.g., encrypted USB drives, password manager). Do not commit it to a public Git repository.

Step 2: Configure Secure Boot in menuconfig

  1. Open your project and launch the ESP-IDF: SDK Configuration editor (menuconfig).
  2. Navigate to Security features --->.
  3. Select Enable hardware secure boot in bootloader (Secure Boot V2).
  4. For the Secure boot private key (PEM file) option, enter the full, absolute path to the my_secure_boot_key.pem file you just created.
  5. Set the Secure bootloader mode to (One-time flash (recommended)).
  6. Save the configuration and exit.

Step 3: Build, Flash, and Enable Secure Boot

This step is irreversible. The first time you flash with these settings, the eFuses will be burned.

  1. Build the project. The build system will now automatically sign the bootloader and application binaries using your private key.idf.py build
  2. Flash the device.idf.py -p (YOUR_PORT) flash
  3. Monitor the device output closely.idf.py -p (YOUR_PORT) monitor

You will see logs similar to the following on the very first boot:

Plaintext
...
I (32) boot: ESP-IDF v5.x-dirty 2nd stage bootloader
...
I (73) esp_image: segment 0: paddr=0x00010020 vaddr=0x3c020020 size=0x052d8 h..
...
I (86) boot: Checking secure boot...
I (90) boot: blowing secure boot efuse...
I (95) efuse: Burning EFUSE_BLK2_R_DIS...
I (95) efuse: Burning EFUSE_WR_DIS_ABS_DONE_0...
I (100) efuse: Burning abstract 0
I (105) boot: Secure boot is enabled.
...
I (110) boot: Loading app from partition at offset 0x20000
I (111) secure_boot_v2: Verifying secure boot signature
I (134) secure_boot_v2: Signature verified successfully.
...
Hello world!

Log Analysis:

  1. blowing secure boot efuse...: The bootloader detects it’s the first run.
  2. Burning EFUSE...: It permanently writes the public key digest to the eFuse block and burns the ABS_DONE_0 eFuse to enable Secure Boot mode.
  3. Secure boot is enabled.: Confirmation that the process is complete and irreversible.
  4. Verifying secure boot signature: On every boot from now on, you will see this line.
  5. Signature verified successfully.: The bootloader has successfully authenticated the application firmware against the hardware root of trust.

Step 4: Updating Firmware with Secure Boot Active

Updating is seamless. The build system remembers the path to your private key and automatically signs every new build.

Simply make your code changes, rebuild, and re-flash:

Bash
idf.py build
idf.py -p (YOUR_PORT) flash

The device will boot the new firmware after verifying its signature. If you were to try flashing an unsigned binary, or one signed with a different key, the bootloader would reject it.

Variant Notes

The Secure Boot V2 (RSA-based) scheme is standardized across all modern ESP32 variants.

  • ESP32 (all versions), ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, ESP32-H2: All these chips support Secure Boot V2. The underlying eFuse blocks and ROM code behavior are consistent. The ESP-IDF framework handles any minor chip-specific configurations, providing a unified user experience.
  • Older ESP32 Revisions (v0, v1): Had a different Secure Boot V1 scheme which is now deprecated. ESP-IDF v5.x defaults to V2, which is more secure and flexible. Unless you are working with very old hardware, you will always be using V2.

Common Mistakes & Troubleshooting Tips

Mistake / Issue Symptom(s) Troubleshooting / Solution
Lost Private Signing Key (.pem file) You can no longer build and sign new firmware that the device will accept. The device is effectively “bricked” with its last working firmware, unable to receive updates. Catastrophic, no recovery. Implement a strict key management policy. Back up the .pem file to multiple secure, offline locations (encrypted USB, vault). This is the master key to your device fleet.
Incorrect Path to Signing Key in Menuconfig The build process fails with an error like “Secure boot signing key not found”. The system cannot locate the .pem file to sign the binaries. Ensure you provide the full, absolute path to the signing key in menuconfig → Security features. Relative paths (e.g., ~/keys/) may not work reliably.
Flashing Unsigned Binaries Post-Enablement Boot fails with an error in the logs like secure_boot_v2: signature verification failed. The bootloader correctly identifies the firmware as inauthentic. Always use idf.py build flash. The build system automatically signs all artifacts. Never try to flash individual, unsigned binaries (e.g., app.bin) with external tools like esptool.py.
Committed Private Key to Public Repo (e.g., GitHub) Your secret key is exposed. Anyone can now sign malicious firmware with your key, and your devices will trust and run it, completely defeating Secure Boot. Immediately consider the key compromised. If you have control over the devices, plan for a firmware update that revokes the compromised key if possible (an advanced topic). For future projects, add the key’s filename to your .gitignore file.
JTAG Debugging Disabled by Default Debugger fails to connect to the target after enabling Secure Boot. This is an intentional security measure. If debugging is required, you can re-enable it in menuconfig. However, this is a security risk for production units, as it may allow an attacker to bypass signature checks.

Exercises

  1. Secure a Project: Take the nvs_read_write example project. Generate a new secure boot key and enable Secure Boot. Flash the device and capture the first boot log. Then, change a string that is written to NVS, rebuild, re-flash, and confirm that the updated (and re-signed) application runs correctly.
  2. Simulate a Failed Update: Using the project from Exercise 1, generate a second, different secure boot key (my_second_key.pem). Change the menuconfig setting to point to this new key. Clean and rebuild the project (idf.py fullclean build). Now, attempt to flash this new, differently-signed firmware to the already-secured device. Observe the monitor output. The device should fail to boot and display an error about signature verification. Analyze this error.

Summary

  • Secure Boot ensures the authenticity and integrity of your firmware, preventing unauthorized or malicious code from running on your device.
  • It is based on RSA digital signatures, using a secret private key (held by the developer) to sign firmware and a public key (on the device) to verify it.
  • A hash of the public key is burned into eFuses, creating a permanent, unchangeable hardware root of trust.
  • Enabling Secure Boot is a permanent, one-way operation that cannot be disabled.
  • The private signing key is your master key. Losing it means you cannot update your devices.
  • Secure Boot (authenticity) and Flash Encryption (confidentiality) are complementary features that should be used together for robust device security.

Further Reading

Related Posts

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top