ESPSECURE.PY(1)

📦
version 4.7.0 · 2 versions
, in debian trixie, ubuntu noble, ubuntu questing

✨ ESPSECURE.PY ✨

okay bestie, you're looking at the manual page for espsecure — it's the ESP32 Secure Boot & Flash Encryption tool, and yeah it's a whole vibe. 💅 This is the User Commands section, so settle in, grab a boba, and let's get into it. 🧋🫶

💖 NAME 💖

espsecure — the ESP32 Secure Boot & Flash Encryption tool. that's her. that's the whole name. iconic. 👑

🌸 DESCRIPTION 🌸

the way you run this is literally just:

usage: espsecure [OPTION] COMMAND

that's it. one command, one dream. 🦋

🎀 command arguments 🎀

ngl this is the main event. and fr fr, if you want the tea on any single one of these, you just run espsecure {command} -h for additional help. it's giving self-serve. 💁♀️

  • digest_secure_bootloader — takes a bootloader binary image plus a secure boot key, and spits out a combined digest+binary that's suitable for flashing along with the precalculated secure boot key. lowkey the whole point. 🔥
  • generate_signing_key — makes you a private key for signing secure boot images, per the secure boot version. the key file comes out in PEM format. Secure Boot V1 gives you an ECDSA NIST256p private key; Secure Boot V2 gives you RSA 3072, ECDSA NIST256p, or ECDSA NIST192p private key. choose your fighter. ⚔️
  • sign_data — signs a data file for use with secure boot. the signing algorithm is deterministic ECDSA w/ SHA-512 (V1), or either RSA-PSS or ECDSA w/ SHA-256 (V2). yes bestie, deterministic. she knows what she's doing. 💅
  • verify_signature — verifies a data file that was previously signed by sign_data, using the public key. trust but verify, always. 🫶
  • extract_public_key — extracts the public verification key for signatures and saves it as a raw binary file. just the public part, keep it cute. 🎀
  • digest_rsa_public_key — generates an SHA-256 digest of the RSA public key. this digest gets burned into the eFuse and it's what asserts the legitimacy of the public key for Secure boot v2. 🔥
  • digest_sbv2_public_key — generates an SHA-256 digest of the public key. this digest is burned into the eFuse and asserts the legitimacy of the public key for Secure boot v2. (yes she's similar to the one above, no we don't make the rules.) ✨
  • signature_info_v2 — reads the signature block and gives you the signature block information. it's giving detective energy. 🔍
  • digest_private_key — generates an SHA-256 digest of the private signing key. this can be used as a reproducible secure bootloader (only secure boot v1) or flash encryption key. very versatile of her. 🌈
  • generate_flash_encryption_key — generates a development-use flash encryption key with random data. dev-use only bestie, don't get it twisted. ⚠️
  • decrypt_flash_data — decrypts some data read from encrypted flash (using a known key). ✨
  • encrypt_flash_data — encrypts some data suitable for encrypted flash (using a known key). the matching set, we love a duo. 💜

💅 options 💅

  • -h, --help — shows this help message and exits. the classic. the icon. the moment you need most. 🫶

🔥 EXAMPLES 🔥

these are copy-paste ready, so go off:

Display device features, SPI flash manufacturer and device ID:

esptool flash_id

Flash ESP8266 Espressif AT v1.6.2 firmware to ESP-WROOM-02 board:

esptool write_flash --flash_mode dio --flash_size 4MB-c1 0x00 boot_v1.7.bin 0x1000 at/1024+1024/user1.2048.new.5.bin 0xfe000 blank.bin 0x3fc000 esp_init_data_default_v08.bin 0x3fe000 blank.bin

Flash ESP32 Espressif AT v1.1.1 firmware to ESP-WROOM-32 board:

esptool write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x20000 at_customize.bin 0x21000 customized_partitions/ble_data.bin 0x24000 customized_partitions/server_cert.bin 0x26000 customized_partitions/server_key.bin 0x28000 customized_partitions/server_ca.bin 0x2a000 customized_partitions/client_cert.bin 0x2c000 customized_partitions/client_key.bin 0x2e000 customized_partitions/client_ca.bin 0xf000 phy_init_data.bin 0x100000 esp-at.bin 0x8000 partitions_at.bin

Display ESP32 efuse state summary:

espefuse --port /dev/ttyUSB0 summary

Generate a flash encryption key:

espsecure generate_flash_encryption_key key.bin

Burn the key to the device (WARNING: one time only operation):

espefuse --port /dev/ttyUSB1 burn_key flash_encryption key.bin
🚨 bestie pause — that burn command is a WARNING: one time only operation. like, one time. only. no takebacks, no undo, no "wait actually". read it twice. 😭

Encrypt flash data:

espsecure encrypt_flash_data --keyfile key.bin --address 0x10000 -o my-app-encrypted.bin my-app.bin

👑 AUTHOR 👑

so esptool.py was started by Fredrik Ahlberg as an unofficial community project, and it's currently maintained by Angus Gratton, supported by Espressif Systems (Shanghai) PTE LTD. this manual page has been produced by Milan Kupcevic <milan@debian.org> for the Debian project and can be used by others. shoutout to the whole squad. 🫶💖

🐛 REPORTING BUGS 🐛

if something's acting up, tell the devs, don't just suffer in silence. communication is key, iykyk. 💅

Copyright © 2014-2017 Fredrik Ahlberg, Angus Gratton, Espressif Systems (Shanghai) PTE LTD, other contributors as noted. License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

no warranty bestie, so like… be normal about it. 🙈

🌈 SEE ALSO 🌈

esptool(1), espefuse(1), espsecure(1) — the whole friend group, go say hi. 💖

and that's the page, babe. 💅 this one's from esptool.py 4.7.0, dated January 2024, and it lives in the ESPSECURE.PY(1) section of the manual. slay, go encrypt something, stay secure, periodt. 👑✨🦋

📦 where this page comes from