wolfBoot is a bare-metal secure bootloader for 32-bit microcontrollers

What wolfBoot is for and the design constraints behind it

The project describes itself as a portable, OS-agnostic, secure bootloader solution for 32-bit microcontrollers, relying on wolfCrypt for firmware authentication and providing firmware update mechanisms. The README states the reason for the minimalist design and the tiny HAL API: because of them, wolfBoot is completely independent from any OS or bare-metal application, and can be easily ported and integrated into existing embedded software projects to provide a secure firmware update mechanism. The architecture is based on RFC 9019, A Firmware Update Architecture for Internet of Things, which is worth noting because it means the update model is not invented here but follows a document that describes how IoT devices should be updated. The topic list tells you the rest of the scope: firmware authentication, firmware verification, key generation, multi-slot partitioning, device management, compact, os-independent and portable. The homepage is wolfssl.com and the manual is published alongside the product.

The feature set, and what each item costs you

The features list is short and each entry carries an architectural decision. Multi-slot partitioning of the flash device gives you somewhere to stage an update while the current firmware still runs. Integrity verification of the firmware images is the hash check. Authenticity verification uses wolfCrypt's Digital Signature Algorithms, which is the cryptographic core. The minimalist Hardware Abstraction Layer interface facilitates portability across different vendors and MCUs. Copy and swap images from secondary slots into the primary slots to consent firmware update operations. In-place chain-loading of the firmware image in the primary slot, which is the mechanism for the bootloader to hand control to the application. Support of a Trusted Platform Module, and measured boot support, which stores the firmware image hash into a TPM Platform Configuration Register. The PCR write is the piece that makes a boot chain attestable after the fact rather than only at boot time, and it is the one feature with an obvious hardware dependency.

What is actually in the repository

The repository contains three things, per the components section. The first is the wolfBoot bootloader itself, described as a memory-safe standalone bare-metal application designed to run on a generic microcontroller, with no dynamic memory allocation mechanism and no linkage to any standard C library besides wolfCrypt. The second is the key generator and image signing tools. The third is bare-metal test applications. Inside the bootloader there are four parts. wolfCrypt verifies the signature of the images. A minimalist Hardware Abstraction Layer, with an implementation provided for the supported target, is in charge for IAP flash access and clock setting on the specific MCU. The core bootloader does the work. And a small application library, in src/libwolfboot.c, is used by the application to interact with the bootloader. The top-level layout matches: src, hal, include, tools, config, docs, port, lib, stage1, test-app, cmake, a zephyr directory, plus CMakeLists.txt, CMakePresets.json, arch.mk, options.mk and a Makefile.

Building it from a clone

If you cloned wolfBoot from GitHub rather than using a release package, you need to initialise and update the git submodules first, since that step is required to pull in the necessary dependencies before building.

git submodule update --init

For the Makefile build, you create a .config file with your build specifications in the wolfBoot root directory, and a number of examples are available inside config/examples. Then you run make keytools to generate the signing and key generation tools, unless you have wolfCrypt-py installed, in which case you can skip that step. Using the provided stm32h7 config, the sequence is three commands.

cp config/examples/stm32h7.config .config
make keytools
make

Documentation for the flash configuration options used in .config lives in docs/compile.md. A CMake build is also supported, with docs in docs/CMake and the cmake includes documented in cmake/README.md. The Makefile itself shows some of the scope: it resolves a Microchip PIC32CZ hardware secure module path, supports GCC, Clang and Armclang toolchains with a TI cl2000 driver exception that rejects the warning flags, has a FLASH_OTP_KEYSTORE option for a one-time-programmable key store, and computes the bootloader partition size from the partition boot address and the architecture flash offset.

What the default make target produces

The build system automation is described step by step, and it is the clearest picture of the artefact you end up with. Using the baremetal test application as the example to create the factory image, running make will create an Ed25519 key pair using the keygen tool, compile the bootloader with the public key generated in that step included in the build, compile the firmware image from the test application in test-app, re-link the firmware to change the entry point to the start address of the primary partition, sign the firmware image using the sign tool, and create a factory image by concatenating the bootloader and the firmware image. The factory image can then be flashed to the target device, and it contains the bootloader and the signed initial firmware at the specified address on the flash. The sign tool transforms a bootable firmware image to comply with the firmware image format required by the bootloader, and the format itself is documented in docs/firmware_image.md. Two things are worth pausing on here. The re-link step exists because the bootloader occupies the first slot, so the application's entry point has to move, and the signature covers the image at that final entry point rather than the original link.

The update path and the application-side library

The upgrading sequence shows how a device updates itself. You compile the new firmware image and link it so that its entry point is at the start address of the primary partition, sign it using the sign tool and the private key generated for the factory image, transfer the image using a secure connection and store it to the secondary firmware slot, and trigger the image swap using the libwolfboot wolfBoot_update_trigger() function. Then you reboot to let the bootloader begin the image swap and confirm the success of the update using the libwolfboot wolfBoot_success() function. Both functions are described in the wolfBoot library API documentation. The application side of this is why src/libwolfboot.c exists: it is the small library the application uses to talk to the bootloader, and the trigger-and-confirm pattern means a failed swap is detectable by the application rather than being an invisible failure. Integration with an existing project follows the same split, with the required steps listed as reference implementation examples in docs/Targets.md, providing a HAL implementation, deciding a flash partition strategy and modifying include/target.h, changing the entry point of the firmware image, equipping the application with the wolfBoot library, compiling a bootable image with a single make command, and the signing and measured boot guides.

Where wolfBoot is the wrong choice

Three limits. The first is the porting work, and it is not small. The bootloader is independent of any OS by design, which means someone has to write the HAL for your MCU, handle in-application programming flash access and clock setting, choose and implement a partition strategy, and rework the application's entry point. The README says a HAL implementation is required, and the Makefile's own contents show how much vendor-specific variation there is, from a Microchip PIC32CZ hardware secure module path to a Microchip FPGA DDR configuration directory and a TI cl2000 toolchain carve-out. The second is the key ceremony, which the project does not take off your hands. The sign and keygen tools are in the repository, but generating an Ed25519 key pair and protecting the private key across the manufacturing and update chain is a process you design, and there is no hosted signing service in the model. The third is scope. This is a bootloader for 32-bit microcontrollers, so it does not cover 64-bit parts, and the feature set has no network stack, no over-the-air update transport of its own, and no device management beyond the update mechanism and the TPM integration. The documented alternatives are different in kind. A vendor bootloader for your specific part is free with the silicon and already trusted by your customers, at the cost of no control over its signing and update behaviour. A hosted secure update service gives you key management, device inventory and fleet rollout, at the cost of a vendor dependency and per-device cost. And a TEE-based approach moves part of the trust anchor into hardware. If your real problem is fleet management rather than signed boot, a secure update service addresses that better than a bootloader does.

Editorial conclusion

Adopt wolfBoot if you are shipping a 32-bit microcontroller product that needs signed firmware and in-field updates, and you have the flash layout and key ceremony worked out. Skip it if your device already has a vendor bootloader you cannot replace, or if you need a hosted or managed signing service, since key handling is on you. Before you commit, read docs/Targets.md for a reference port, decide the partition strategy in include/target.h, and confirm that a TPM is available if you need measured boot.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. wolfSSL/wolfBoot on GitHub