How to manually encrypt the plaintext firmware of the ESP32 device using a fixed key

The requirements are as follows

Encrypting the mass-produced firmware, after encryption you can use the tool to erase the old firmware, and it support repeated flashing the firmware.

Required tools:

• esptool , you can refer to Introduction and use of esptool.py
• Flash download tool

Reference Documentation:

• Flash Encryption
• ESP32-Secure Boot security solution

solution

• Generate Flash encryption key using the esptool command.
• Compile the project to obtain the plaintext firmware.
• Encrypt the plaintext firmware using the Flash encryption key.
• Use the Flash download tool to flash the encrypted firmware.
• Burn the Flash encryption key into the eFuse.
• Write the Flash encryption control bits in eFuse to enable Flash encryption.

---

1、 Use the esptool command to generate a Flash encryption key (key.bin) , for example, the generated encryption key is key.bin:

espsecure.py generate_flash_encryption_key key.bin

---

2、Compile the project to obtain the plaintext firmware, using the hello-world as an example

• Turned on the Flash encryption option in menuconfig, as follows:

menuconfig -> Security features -> Enable flash encryption on boot

• Since Flash encryption increases the size of the bootloader .bin firmware, the offset of the default partition table needs to be adjusted, which is 0x8000, can be adjusted to 0xa000. You can modify the settings for partition_table in menuconfig. As follows:

menuconfig -> Partition Table -> Offset of partition table

• Then compile the project and check the firmware download address corresponding to the compiled firmware. You can find that the download address of hello-world.bin becomes 0x20000

Project build complete. To flash, run this command:
E:\.espressif\python_env\idf4.3_py3.8_env\Scripts\python.exe ..\..\..\components\esptool_py\esptool\esptool.py -p (PORT) -b 460800 --before default_reset --after no_reset --chip esp32c3  write_flash --flash_mode dio --flash_size detect --flash_freq 80m 0x0 build\bootloader\bootloader.bin 0xa000 build\partition_table\partition-table.bin 0x20000 build\hello-world.bin
or run 'idf.py -p (PORT) flash'

3、Using the generated Flash encryption key (key.bin file) to encrypt each individual firmware (bin file) that compiled by project. As follows:

• Using the generated Flash encryption key (key.bin) to encrypt bootloader.bin, and the encrypted bootloader.bin becomes key_bootloader.bin

espsecure.py encrypt_flash_data --keyfile key.bin --address 0x1000 -o key_bootloader.bin build/bootloader/bootloader.bin

• Using the generated Flash encryption key (key.bin) to encrypt partition-table.bin, and the encrypted partition-table.bin becomes key_partition-table.bin

espsecure.py encrypt_flash_data --keyfile key.bin --address 0xa000 -o key_partition-table.bin build/partition_table/partition-table.bin

• Using the generated Flash encryption key (key.bin) to encrypt hello_world.bin, and the encrypted hello_world.bin becomes key_hello-world.bin

espsecure.py encrypt_flash_data --keyfile key.bin --address 0x20000 -o key_hello-world.bin build/hello_world.bin

---

4、Use the Flash download tool to flash the encrypted firmware

• According to the corresponding download address of the firmware compiled by project, program the encrypted firmware (encrypted bin file), use the esptool to download the encrypted firmware as follows:

esptool.py -b 460800 --before default_reset --after no_reset --chip esp32 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 key_bootloader.bin 0xa000 key_partition-table.bin 0x20000 key_hello-world.bin

Note:

This step to download the encryption firmware can also be downloaded directly using the Flash Download Tool as follows:

5、Burn the Flash encryption key into the eFuse:

• Using the esptool, run the following command to burn the Flash encryption key (key.bin) into eFuse:

espefuse.py burn_key flash_encryption key.bin

---

6、Write the Flash encryption control bits in eFuse to enable Flash encryption

• Use the esptool tool to turn on the Control Bits for Flash Encryption in Efuse:

espefuse.py burn_efuse FLASH_CRYPT_CONFIG 0xF FLASH_CRYPT_CNT 1 

---

Instructions

• If the Flash encryption key ( key.bin) is not written in Efuse or not turn on the Control Bits for Flash encryption in Efuse, the encrypted “firmware” (bin file) does not boot properly.

• After Flash encryption is enabled, the Flash Download Tool cannot be used to reprogram the firmware and erase the firmware, but the esptool tool is supported to reprogram the firmware and erase the firmware.

• For encrypted modules encrypted by Flash to reprogram firmware, the reprogram firmware requires to turn on the configuration option of “Flash Encryption” in menuconfig, and use the same encryption key (key.bin) as the old firmware to encrypt and flash, so that the reprogram firmware can boot properly.

• Burning encryption keys in Efuse is non-erasable, so new keys cannot be reprogrammed.

• This solution meets the requirements that it can also use the esptool tool to reprogram the firmware, erase, read Flash operation on the module after the module production firmware is encrypted, but the read firmware is encrypted firmware. If the new module does not flash the key (key.bin) corresponding to the encryption firmware, only reprogram the encrypted firmware to the new module, it can’t boot properly.