In order to encrypt your firmware, you will need to build it from source. Our firmware source code can be found here, along with instructions on how to build it. Below you will find specific instructions on how generate keys, build and flash encrypted firmware.
- Obtain keys (for Secure Boot and Flash Encryption)
- Flash keys and parameters in efuses
- Compile bootloader and application with
- Flash: bootloader-digest at address 0x0 and encrypted; all the others (partitions and application) encrypted, too.
Firstly you will need to setup the tool chain and download the source code. detailed instructions on how to achieve this can be found here. Once you have complete this, you will need to open a terminal in the esp32 folder of the firmware source code repo.
Next you will need keys for Flash Encryption and Secure Boot; they can be generated randomly with the following commands:
python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_flash_encryption_key flash_encryption_key.bin python $IDF_PATH/components/esptool_py/esptool/espsecure.py generate_signing_key secure_boot_signing_key.pem
The Secure Boot key
secure_boot_signing_key.pem has to be transformed into
secure-bootloader-key.bin, to be burnt into efuses. This can be done in
python $IDF_PATH/components/esptool_py/esptool/espsecure.py extract_public_key --keyfile secure_boot_signing_key.pem signature_verification_key.bin
or, as an artifact of the make build process, on the same directory level as Makefile
make BOARD=GPY SECURE=on TARGET=boot
To flash the keys (
into the efuses (write and read protected) run the following commands (ignoring
the lines that start with
Note: Irreversible operations
# Burning Encryption Key python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_key flash_encryption flash_encryption_key.bin # Burning Secure Boot Key python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_key secure_boot secure-bootloader-key.bin # Enabling Flash Encryption mechanism python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse FLASH_CRYPT_CNT # Configuring Flash Encryption to use all address bits togheter with Encryption key (max value 0x0F) python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse FLASH_CRYPT_CONFIG 0x0F # Enabling Secure Boot mechanism python $IDF_PATH/components/esptool_py/esptool/espefuse.py --port /dev/ttyUSB0 burn_efuse ABS_DONE_0
If the keys are not written in efuse, before flashing the bootloader, then random keys will be generated by the ESP32, they can never be read nor re-written, so bootloader can never be updated. Even more, the application can be re-flashed (by USB) just 3 more times.
make BOARD=GPY SECURE=on SECURE_KEY=secure_boot_signing_key.pem ENCRYPT_KEY=flash_encryption_key.bin TARGET=[boot|app]
SECURE=onis the main flag; it's not optional
SECURE=onthe following defaults are set:
- encryption is enable
secure_boot_signing_key.pemis the secure boot key, located relatively to Makefile
flash_encryption_key.binis the flash encryption key, located relatively to Makefile
For flashing the bootloader digest and the encrypted versions of all binaries:
make BOARD=GPY SECURE=on flash
For flashing the
bootloader-reflash-digest.bin has to be written at address 0x0,
instead of the
bootloader.bin (at address
Build is done using
SECURE=on option; additionally, all the binaries are
make BOARD=GPY clean make BOARD=GPY SECURE=on TARGET=boot make BOARD=GPY SECURE=on TARGET=app make BOARD=GPY SECURE=on flash
Manual flash command:
python $IDF_PATH/components/esptool_py/esptool/esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before no_reset --after no_reset write_flash -z --flash_mode dio --flash_freq 80m --flash_size detect 0x0 build/GPY/release/bootloader/bootloader-reflash-digest.bin_enc 0x8000 build/GPY/release/lib/partitions.bin_enc 0x10000 build/GPY/release/gpy.bin_enc_0x10000
The OTA should be done using the pre-encrypted application image.
Because the encryption is done based on the physical flash address, there are 2 application binaries generated:
- gpy.bin_enc_0x10000 which has to be written at default factory address: 0x10000
- gpy.bin_enc_0x1A0000 which has to be written at the ota_0 partition address (0x1A0000)
Hint: on micropython interface, the method
pycom.ota_slot() responds with the address of the next OTA partition available (either 0x10000 or 0x1A0000).