Bootloader Explained
embassy-boot
is a lightweight bootloader designed for power-failure safe firmware application upgrades, featuring trial boot and rollback capabilities.
The bootloader can be used as a library or flashed directly if you are satisfied with the default configuration and features.
By design, the bootloader does not provide any networking capabilities. Network functionalities for obtaining new firmware can be provided by the user application, using the bootloader as a library to update the firmware, or by using the bootloader as a library and adding this functionality yourself.
The bootloader supports internal and external flash by depending on the embedded-storage
trait. The bootloader optionally supports verifying digitally signed firmware (recommended for enhanced security).
Hardware Support
The bootloader supports:
- nRF52 with and without SoftDevice
- STM32 L4, WB, WL, L1, L0, F3, F7, and H7 series
- Raspberry Pi: RP2040
Generally, the bootloader can work on any platform that implements the embedded-storage
trait for its internal flash, but may require custom initialization code to function correctly.
STM32L0x1 devices require enabling the flash-erase-zero
feature.
Design
The bootloader divides the storage into 4 main partitions, which are configured when creating the bootloader instance or via linker script:
-
BOOTLOADER - Location where the bootloader is placed. The bootloader itself consumes around 8kB of flash, but increasing it to 24kB if you have space available will allow you to run the bootloader with probe-rs if you need to debug it.
-
ACTIVE - Location where the main application is placed. The bootloader will attempt to load the application at the start of this partition. This partition is only written to by the bootloader. The size required for this partition depends on the size of your application.
-
DFU - Location where the application to be swapped in is placed. This partition is written to by the application. This partition must be at least 1 page larger than the ACTIVE partition, as the swapping algorithm uses the extra space to ensure power-safe copying of data: +
Partition Size~dfu~= Partition Size~active~ + Page Size~active~
+ All values are specified in bytes. -
BOOTLOADER STATE - Location where the bootloader stores the current state, describing whether the active and dfu partitions need to be swapped. When new firmware has been written to the DFU partition, a magic field is written indicating that the bootloader should swap partitions. This partition must be able to store the magic field as well as partition swapping progress. The partition size is given by: +
Partition Size~state~ = Write Size~state~ + (2 × Partition Size~active~ / Page Size~active~)
+ All values are specified in bytes.
The partitions for ACTIVE (+BOOTLOADER), DFU, and BOOTLOADER_STATE can be placed in separate flash memories. The page size used by the bootloader is determined by the least common multiple of the ACTIVE and DFU page sizes. The BOOTLOADER_STATE partition must be large enough to store one word per page in the ACTIVE and DFU partitions.
The bootloader has a platform-agnostic part that implements the power-failure safe swapping algorithm, given the boundaries of the partition setup. The platform-specific part is a minimal shim that provides additional functionality such as a watchdog or support for nRF52 SoftDevice.
Note: The linker scripts for the application and bootloader look similar, but the FLASH region for the bootloader must point to the BOOTLOADER partition, and the FLASH region for the application must point to the ACTIVE partition.
FirmwareUpdater
FirmwareUpdater
is an object for conveniently flashing firmware to the DFU partition and then marking it as ready to swap with the active partition on the next reset. Its main methods are write_firmware
, which is called once per flash "write block" size (typically 4KiB), and mark_updated
, which is the final call.
Verification
The bootloader supports verifying firmware that has been flashed to the DFU partition. Verification requires that the firmware has been digitally signed using ed25519 signatures. When verification is enabled, the FirmwareUpdater::verify_and_mark_updated
method is called instead of mark_updated
. It takes the public key and signature, as well as the actual length of the flashed firmware. If verification fails, the firmware will not be marked as updated and will thus be rejected.
The signature is typically passed alongside the firmware to be updated, rather than written to flash. How to provide the signature is the responsibility of the firmware.
To enable verification, use the ed25519-dalek
or ed25519-salty
features when depending on the embassy-boot
crate. We currently recommend ed25519-salty
as it is smaller.
Hints about keys and using ed25519 signatures
Ed25519 is a public-key signature system, and it is your responsibility to keep the private key safe. We recommend embedding the public key into your program so that it can easily be passed to verify_and_mark_updated
. Here is an example of declaring the public key in your firmware:
static PUBLIC_SIGNING_KEY: &[u8] = include_bytes!("key.pub");
Signatures are typically passed alongside the firmware, e.g. as an attachment.
Ed25519 keys can be generated by multiple tools. We recommend signify as it is widely used to sign and verify OpenBSD releases, and is simple to use.
The following set of bash commands can be used on Unix platforms to generate public and private keys, and produce a local key.pub
file with the signify
file header removed. Declare the SECRETS_DIR
environment variable to a secure location.
signify -G -n -p $SECRETS_DIR/key.pub -s $SECRETS_DIR/key.sec
tail -n1 $SECRETS_DIR/key.pub | base64 -d -i - | dd ibs=10 skip=1 > key.pub
chmod 700 $SECRETS_DIR/key.sec
export SECRET_SIGNING_KEY=$(tail -n1 $SECRETS_DIR/key.sec)
Then, to sign your firmware, given a declaration of FIRMWARE_DIR
and a firmware filename of myfirmware
:
shasum -a 512 -b $FIRMWARE_DIR/myfirmware | head -c128 | xxd -p -r > $SECRETS_DIR/message.txt
signify -S -s $SECRETS_DIR/key.sec -m $SECRETS_DIR/message.txt -x $SECRETS_DIR/message.txt.sig
cp $FIRMWARE_DIR/myfirmware $FIRMWARE_DIR/myfirmware+signed
tail -n1 $SECRETS_DIR/message.txt.sig | base64 -d -i - | dd ibs=10 skip=1 >> $FIRMWARE_DIR/myfirmware+signed
Remember to protect the $SECRETS_DIR/key.sec
key, as leaking it means another party can sign your firmware.