This tutorial explains the setup required to enable Secure Boot & Flash encryption in the firmware. Please first follow the tutorial Building the firmware from source to make sure the firmware can be built on your system and all necessary tools and frameworks are installed.
It is also advised that you review the Espressif Tutorials about Secure Boot, Flash Encryption and NVS encryption. Enabling security features on your board is permanent and cannot be undone. If done improperly, you can permanently loose access to your device! We highly recommend you book a 1h free consultation with us as part of the Starter Kit purchase. Please get in contact with your sales channel to book your free consultation.
Flash encryption will not encrypt the nvs partitions. Instead, all nvs variables will be erased during the encryption process. Flashing encrypted nvs data is outside the scope of this tutorial.
Step 1: Checkout this branch of the source SDK: https://github.com/sg-wireless/sg-sdk/tree/security
cd sg-sdk
git remote update
git checkout security
Step2: Create the Secure Boot signature (make sure you backup this signature. You will not be able to sign firmware for your device without this file!):
. ext/esp-idf/export.sh
espsecure.py generate_signing_key --version 2 secure_boot_signing_key.pem
Step3: Clean and build the firmware:
./fw_builder.sh --board SGW3501-F1-StarterKit clean
./fw_builder.sh --board SGW3501-F1-StarterKit build
Step4: Erase the board and then do a full-flash in order to flash the bootloader and firmware
./fw_builder.sh --board SGW3501-F1-StarterKit erase --port /dev/ttyUSB0
./fw_builder.sh --board SGW3501-F1-StarterKit full-flash --port /dev/ttyUSB0
It is important to use the full-flash command to flash the new bootloader with secure boot enabled onto the device. The IDF build system does not flash the bootloader by default when secure boot is enabled!
IMPORTANT: After your device is flashed, the system will encrypt the partitions on the device. Due to the large flash size (16MB) and the large file system (8MB), this takes several minutes, where the device appears to be unresponsive! DO NOT INTERRUPT / RESET the board. Please wait at least 5 minutes after flashing before investigating!
When flashing the first board, it can be helpful to enable bootloader debugging. This can be done by modifying the file src/platforms/F1/configs/sdkconfig.board
# Uncomment for additional bootloader debugging
CONFIG_BOOTLOADER_LOG_LEVEL_INFO=y
CONFIG_BOOTLOADER_LOG_LEVEL=3
You can also find the secure boot and flash encryption settings in the file:
# SECURE BOOT SETTINGS
CONFIG_SECURE_SIGNED_ON_BOOT=y
CONFIG_SECURE_SIGNED_ON_UPDATE=y
CONFIG_SECURE_SIGNED_APPS=y
CONFIG_SECURE_BOOT_SUPPORTS_RSA=y
CONFIG_SECURE_TARGET_HAS_SECURE_ROM_DL_MODE=y
CONFIG_SECURE_SIGNED_APPS_RSA_SCHEME=y
CONFIG_SECURE_BOOT=y
CONFIG_SECURE_BOOT_V2_ENABLED=y
CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES=y
CONFIG_SECURE_BOOT_SIGNING_KEY="../../../secure_boot_signing_key.pem"
CONFIG_SECURE_BOOT_ENABLE_AGGRESSIVE_KEY_REVOKE=y
# CONFIG_SECURE_BOOT_INSECURE is not set
# FLASH ENCRYPTION SETTINGS
CONFIG_SECURE_FLASH_ENC_ENABLED=y
# CONFIG_SECURE_FLASH_ENCRYPTION_AES128 is not set
CONFIG_SECURE_FLASH_ENCRYPTION_AES256=y
# CONFIG_SECURE_FLASH_ENCRYPTION_MODE_DEVELOPMENT is not set
CONFIG_SECURE_FLASH_ENCRYPTION_MODE_RELEASE=y
CONFIG_SECURE_FLASH_CHECK_ENC_EN_IN_APP=y
# CONFIG_SECURE_DISABLE_ROM_DL_MODE is not set
CONFIG_SECURE_ENABLE_SECURE_ROM_DL_MODE=y
# CONFIG_SECURE_INSECURE_ALLOW_DL_MODE is not set
As you can see, the file is configured for “release” level encryption, with on-board generated random keys that are unique per device. You can use less secure options with pre-generated keys that will allow you to re-flash the device using esptool.
When using the configuration as above, you cannot flash the device with esptool again. The only way to update the firmware on the device is via an OTA update. An example to flash a new firmware OTA is (this example assumes a WiFi or LTE connection in PPP mode is already establed):
import fuota, urequests
fuota.start()
req = urequests.get('http://10.0.221.8:8000/application.bin')
fuota.write(req.content)
fuota.finish()
import machine
machine.reset()
The application.bin file can be found at ./build/sdk-default/F1/SGW3501-F1-StarterKit/micropython/application.bin
Please note that the application.bin file needs to be signed with the secure boot signature created in step 2 above. Trying to flash a firmware without valid signature will revoke your secure boot signing key and may permanently disable your device!