Customized ad-hoc secure boot with wolfBoot

wolfBoot is known for being the universal secure bootloader for all types of embedded systems.

While initially targeting 32-bit microcontrollers, wolfBoot has grown into a full framework to implement secure boot solutions on a wide range of different systems and architectures.

This is mostly due to wolfBoot modularity and flexibility, which makes our solution easy to reshape and adapt to the most peculiar use cases. Here are a few examples of customizations we have facilitated in the past, taken from real-life use cases.

Update images stored on external devices

This type of customization is perhaps the most popular. wolfBoot offers an interface to interact with external storage devices or anything that can be abstracted as such: the “ext_flash” interface.

Ext_flash is an interface that connects wolfBoot to a driver that implements the following function calls, to access the content of specific storage devices:






On microprocessor-based embedded systems, ‘external’ devices are often the only solution, requiring specific drivers to access the kernel images on different supports (USB, SD, eMMC, SSD, etc.). Microcontroller architectures often integrate external NOR SPI/QSPI flash memories that can be used as persistent storage, where generally it’s not possible to execute code in place.

wolfBoot has an additional layer directly supporting several types of SPI flash memory chips. The SPI support is also implemented on top of the ext_flash API interface, and provides another level of abstraction. In this case porting to a new target with an SPI controller only requires to implement the following single SPI transfer functions, and the SPI layer will link the required functions to access the flash through this interface:







SPI access is just one of the possibilities available in wolfBoot to extend the support to any  non-volatile memory, and beyond.

Update images downloaded on-demand from neighbor systems

By design choice, wolfBoot does not include any network stack or communication capabilities besides the access to storage devices and internal flash memory. This is an advantage both in terms of security because it makes the attack surface very small, and from the safety point of view keeping all the structures and code flow simple to follow and predictable.

In some cases it’s required to communicate with other systems during the boot stage, because the firmware image or the updates received may be stored elsewhere, avoiding to split the flash memory to make room for a second partition. In these cases, wolfBoot may be required to open a communication channel (usually through a serial bus such as UART or SPI) to retrieve the firmware images from a neighbor system. This is in fact a rather common requirement when wolfBoot is securing the boot procedure on asymmetric multiprocessor systems or in general systems with multiple heterogeneous cores.

The recommended way to access remote content from wolfBoot consists in defining a custom ext_flash driver that abstracts a virtual addressable memory space. wolfBoot codebase contains an example of ext_uart driver running the client endpoint connecting to the uart_flash_server POSIX application provided, that can export signed and encrypted files for wolfBoot to handle and stage. EXT_UART is yet again one of the possible modes to extend the external flash support to both physical storage supports and virtualized abstractions.

Third-party key provisioning

Provisioning keys is a process that may involve third party tools and entities that generate, store and use the main private key to sign the firmware images. Thanks to the flexibility of the key tools distributed with wolfBoot, keypairs can be both generated or imported (in their public format) within the signing process. While the public keys must all be available and accessible by wolfBoot at run time, the private keys are used to sign the header of each authentic firmware.

The actual signature operation can be detached from the manifest header composition, by splitting the two phases. This way the signing is performed by an external tool, and the private key does not need to be accessed during the operation.

For more information on the possibilities of customizing the signing procedure, please see wolfBoot signing tools documentation.

Storing keys in a secure vault

Storing the public keys used to authenticate the firmware in a secure, write-protected area of persistent memory is the most important security requirement for proper secure-boot mechanism. In many cases it is sufficient to execute wolfBoot from a write-protected area, and keep the keys stored along with the bootloader code, in a C array. This is the default mechanism implemented in wolfBoot.

When the keygen tool generates or imports public keys, it creates two copies of the local archive of the public keys needed at runtime for signature verification, in two different formats. The C array (keystore.c), to be built in the bootloader image, and a binary file (keystore.der) containing the same structure in binary format.

By excluding keystore.c, it is possible to upload the content of keystore.der into a dedicated secure or write-protected storage. A driver to access the secure vault at runtime must be provided, through an API exporting three functions for wolfBoot to retrieve the public keys, their sizes and their permissions mask. Using a separate abstraction layer for the keystore provides an interface that can be customized beyond classic secure element or TPM interactions, to design a more complex structure to handle keys at runtime. More information available in the wolfBoot documentation page about keystore structure.

Unique partition/images and keys combination

Multiple-stage boot layouts can get very complex. Our development team has learned a lot when designing the boot process involving a set of partitions and firmware images with different levels of access permissions for the first time. Since then, we have dealt with several scenarios where multiple actors had to be capable of updating only one subset of partitions with firmware authenticated with specific subsets of public keys.

Consider the following scenario: an embedded device with a secure bootloader and two partitions: a “system” partition (perhaps running in secure mode from a TEE) and an “application” partition, containing configurable software that can be uploaded by a registered user that owns or has access to the device. Two separate keys are needed in this case: the user should only be able to send signed updates for the application partition, while the manufacturer must be able to update the system software (and the bootloader itself, if needed). The two levels of privilege in this case require two separate keypairs, the first one can be associated with the user, and the second with more powers should be kept by the manufacturer.

The latest wolfBoot, thanks to the keystore structure, supports up to 15 target partitions, and each one of these can be authenticated using one or more public keys from the keystore.

A firmware package in wolfBoot is always associated with an identification number (id) from 0 to 15, indicating the partition where the firmware must be installed. In the scenario described above, the ‘system’ would have id=1 and the ‘application’ software is associated with id=2. wolfBoot reserves id=0 for self-update procedure, i.e. update packages containing a new (signed) version of wolfBoot itself.

This mechanism allows the update mechanism to use the same update partition as temporary storage for all the updates, because wolfBoot will parse the incoming package and parse the manifest header to process the package using the right keys. The public key object elements in the keystore described earlier contain a bit mask that associates each key to the single target partition ids.

“Non-secure” boot

wolfBoot supports many different combinations of public key algorithms and key sizes. However, In some cases, authenticating the firmware is not a requirement. wolfBoot works properly when compiled with SIGN=NONE, excluding only the signature verification part, and keeping all the other features to facilitate the update, roll back in case of failure and verify the integrity of the firmware image after the transfer using SHA. That is, wolfBoot can be used as a non-secure bootloader, with a footprint of a few KB and very little impact on boot time. Especially useful in very small low-power systems with a tight amount of resources and CPU cycles.

wolfBoot as library: adding secure boot to legacy bootloaders

Among our customers, many have been upgrading older products and devices, reusing legacy software from previous versions, while stepping ahead with the security requirements which usually means adding a secure boot solution.

While starting a new bootloader from scratch is often an underestimated task from the development and testing point of view, many development teams rely on existing solutions that have been maintained and deployed on the field for years. Some custom bootloader solutions include network communication, sometimes with proprietary protocols and data links which would require a major effort to integrate into a vanilla wolfBoot. On the other hand, most of these legacy solutions lack the needed security features to implement cryptographic secure boot.

For this reason we have introduced the possibility to build wolfBoot as a library. Instead of providing the entire bootloader implementation, including build-up, staging, specific hardware access and customized flows, ‘wolfBoot as library’ is completely portable anywhere and provides easy interfaces to parse the manifest header, check versioning, verify an image loaded or mapped in memory for integrity and authenticity against the provided keystore. The key tools on the hosts can be used exactly in the same way as with the full wolfBoot installation, as the format remains the same and it is completely independent from the hardware or the architecture. To learn more about using wolfBoot as a library, check the documentation page about the library API.

Find out more about wolfBoot! Download the source code and documentation from our download page], or clone the repository from github. If you have any questions, comments or suggestions, send us an email at