{"id":25099547,"url":"https://github.com/dattasaurabh82/esp32_secure_boot","last_synced_at":"2025-10-03T21:22:46.566Z","repository":{"id":276131521,"uuid":"928316710","full_name":"dattasaurabh82/esp32_secure_boot","owner":"dattasaurabh82","description":"Secure boot ensures that our ESP32 only runs firmware that we have authorized. This repository is a tutorial on how to do just that","archived":false,"fork":false,"pushed_at":"2025-02-06T12:56:06.000Z","size":20,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-10T06:53:19.717Z","etag":null,"topics":["esp32","secure-coding","secureboot"],"latest_commit_sha":null,"homepage":"https://docs.espressif.com/projects/esp-idf/en/stable/esp32/security/secure-boot-v2.html","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dattasaurabh82.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-06T12:42:56.000Z","updated_at":"2025-02-07T10:00:48.000Z","dependencies_parsed_at":"2025-02-06T13:45:30.907Z","dependency_job_id":"3a0e8ff0-9d1a-40b3-91d3-cd73695fc017","html_url":"https://github.com/dattasaurabh82/esp32_secure_boot","commit_stats":null,"previous_names":["dattasaurabh82/esp32_secure_boot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dattasaurabh82/esp32_secure_boot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dattasaurabh82%2Fesp32_secure_boot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dattasaurabh82%2Fesp32_secure_boot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dattasaurabh82%2Fesp32_secure_boot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dattasaurabh82%2Fesp32_secure_boot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dattasaurabh82","download_url":"https://codeload.github.com/dattasaurabh82/esp32_secure_boot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dattasaurabh82%2Fesp32_secure_boot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260599019,"owners_count":23034430,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","secure-coding","secureboot"],"created_at":"2025-02-07T19:21:51.402Z","updated_at":"2025-10-03T21:22:41.548Z","avatar_url":"https://github.com/dattasaurabh82.png","language":"Shell","readme":"# ESP32 Secure Boot Guide\n\n## Focus hardware chipset\n\n`ESP32-H2`\n\n\u003e But the shell script and commands can be adopted for any ESP32 chipset that supports secure boot\n\nSecure boot ensures that our ESP32-H2 only runs firmware that we have authorized. \n\n## Advantages\n\n- The RSA-PSS's public key is stored on the device. The corresponding RSA-PSS private key is kept at a secret place and is never accessed by the device.\n- Only one public key can be generated and stored in the chip during manufacturing.\n- The same image format and signature verification method is applied for applications and the second stage bootloader.\n- No secrets are stored on the device. Therefore, it is immune to passive side-channel attacks, e.g., timing or power analysis.\n\nWhen enabled:\n\n- Only firmware signed with your private key will be accepted\n- Prevents unauthorized or malicious code from running\n- Protects against firmware tampering and unauthorized updates\n- _Once enabled, cannot be disabled (permanent security feature)_\n\n## Key points\n\n- Requires initial setup with a signing key\n- All firmware updates must be signed\n- Provides hardware-level security\n- Essential for IoT devices requiring secure deployments\n\n\u003e 💡 Need local system installation.\n\n## 1. Initial Secure Boot Setup (One Time Only)\n\n1. Generate \u0026 Process signing key:\n\n```bash\n# In your project directory\n# 1. Generate signing key, if it is the first time and we do not have the secure_boot_signing_key.pem\nespsecure.py generate_signing_key secure_boot_signing_key.pem\n\n# 2. Process the public key for efuse:\nespsecure.py digest_sbv2_public_key --keyfile secure_boot_signing_key.pem --output secure_boot_digest.bin\n```\n\n1. Burn the key and enable secure boot:\n\n\u003e 💡 Can’t be un-done !!\n\n```bash\n# Set key purpose\nespefuse.py --port \u003cPORT\u003e burn_efuse KEY_PURPOSE_0 SECURE_BOOT_DIGEST0\n\n# Burn the key\nespefuse.py --port \u003cPORT\u003e burn_key BLOCK_KEY0 secure_boot_digest.bin SECURE_BOOT_DIGEST0\n\n# Enable secure boot\nespefuse.py --port \u003cPORT\u003e burn_efuse SECURE_BOOT_EN 1\n```\n\n## 2. Compiling (Every Update)\n\n```bash\n# Clean binary directory\nrm -rf binary\nmkdir binary\n\n# Compile\narduino-cli compile -v --fqbn esp32:esp32:esp32h2:UploadSpeed=921600,CDCOnBoot=default,FlashFreq=64,FlashMode=qio,FlashSize=4M,PartitionScheme=min_spiffs,DebugLevel=none,EraseFlash=all,JTAGAdapter=default,ZigbeeMode=default --output-dir binary .\n```\n\n## 3. Signing Binaries (Every Update)\n\n```bash\n# Sign bootloader\nespsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output binary/\u003cSKETCH_NAME\u003e.ino.signed.bootloader.bin binary/\u003cSKETCH_NAME\u003e.ino.bootloader.bin\n\n# Sign partition table\nespsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output binary/\u003cSKETCH_NAME\u003e.ino.signed.partitions.bin binary/\u003cSKETCH_NAME\u003e.ino.partitions.bin\n\n# Sign application\nespsecure.py sign_data --version 2 --keyfile secure_boot_signing_key.pem --output binary/\u003cSKETCH_NAME\u003e.ino.signed.bin binary/\u003cSKETCH_NAME\u003e.ino.bin\n```\n\n## 4. Uploading (Every Update)\n\n4.1. From Terminal \n\n\u003e Can't use `arduino-cli`\n\n```bash\n# For esp32-h2, as an example \n\nesptool.py --chip esp32h2 --port \u003cPORT\u003e --baud 921600 \\\n--before default_reset --after hard_reset write_flash -e -z --flash_mode keep \\\n--flash_freq keep --flash_size 4MB --force \\\n0x0 \"binary/\u003cSKETCH_NAME\u003e.ino.signed.bootloader.bin\" \\\n0x8000 \"binary/\u003cSKETCH_NAME\u003e.ino.signed.partitions.bin\" \\\n0xe000 \"/Users/saurabhdatta/Library/Arduino15/packages/esp32/hardware/esp32/3.0.7/tools/partitions/boot_app0.bin\" \\\n0x10000 \"binary/\u003cSKETCH_NAME\u003e.ino.signed.bin\"\n```\n\n\u003e 💡 Note! if `—-force` is not used, it will show an error: `A fatal error occurred: Secure Boot detected, writing to flash regions \u003c 0x8000 is disabled to protect the bootloader.`\n\u003e\n\u003e This is expected and good - it shows the secure boot protection is working!\n\u003e\n\u003e Using `--force` is okay in this case because we're uploading signed binaries.\n\n\n4.2. From web tool: [dattasaurabh82.github.io/webespflasher/](https://dattasaurabh82.github.io/webespflasher/)\n\n## But that's a lot of manual steps\n\nYes and so, the manual steps 2 and 4 can be made faster with a helper script called [secure_boot_process.sh](secure_boot_process.sh)\n\nJust do:\n\n```bash\n# For esp32-h2, as an example\n# Adopt the script and the cmd settings for your chip set \n\n./secure_boot_process.sh --port \u003cPORT\u003e\n\n# compiles, signs and uploads signed binaries\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdattasaurabh82%2Fesp32_secure_boot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdattasaurabh82%2Fesp32_secure_boot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdattasaurabh82%2Fesp32_secure_boot/lists"}