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.
efuses
make SECURE=on
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 2 ways:
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 (flash_encryption_key.bin
and secure-bootloader-key.bin
) 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 together 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=on
is the main flag; it’s not optionalSECURE=on
the following defaults are set:
secure_boot_signing_key.pem
is the secure boot key, located relatively to Makefileflash_encryption_key.bin
is the flash encryption key, located relatively to MakefileFor 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 0x1000
).
Build is done using SECURE=on
option; additionally, all the binaries are pre-encrypted.
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
).