wolfBoot

wolfSSL Secure Bootloader (Home page, Manual, wolfBoot-examples)

wolfBoot is a portable, OS-agnostic, secure bootloader solution for 32-bit microcontrollers, relying on wolfCrypt for firmware authentication, providing firmware update mechanisms.

Due to the minimalist design of the bootloader and the tiny HAL API, wolfBoot is completely independent from any OS or bare-metal application, and can be easily ported and integrated in existing embedded software projects to provide a secure firmware update mechanism.

Design based on RFC 9019 - A Firmware Update Architecture for Internet of Things.

Features

Multi-slot partitioning of the flash device
Integrity verification of the firmware image(s)
Authenticity verification of the firmware image(s) using wolfCrypt's Digital Signature Algorithms (DSA)
Minimalist hardware abstraction layer (HAL) interface to facilitate portability across different vendors/MCUs
Copy/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
Support of Trusted Platform Module(TPM)
Measured boot support, storing of the firmware image hash into a TPM Platform Configuration Register(PCR)

Components

This repository contains the following components:

the wolfBoot bootloader
key generator and image signing tools (requires python 3.x and wolfcrypt-py https://github.com/wolfSSL/wolfcrypt-py)
Baremetal test applications

wolfBoot bootloader

wolfBoot is a memory-safe standalone bare-metal application, designed to run on a generic microcontroller, with no dynamic memory allocation mechanism or linkage to any standard C library besides wolfCrypt.

The bootloader consists of the following components:

wolfCrypt, which is used to verify the signature of the images
A minimalist Hardware Abstraction Layer, with an implementation provided for the supported target, which is in charge for IAP flash access and clock setting on the specific MCU
The core bootloader
A small application library used by the application to interact with the bootloader src/libwolfboot.c

Requirements

Ensure the proper toolchain is installed. See the docs for platform-specific details.

Integrating wolfBoot in an existing project

Required steps

See docs/Targets.md for reference implementation examples.
Provide a HAL implementation for the target platform (see Hardware Abstraction Layer)
Decide a flash partition strategy and modify include/target.h accordingly (see Flash partitions)
Change the entry point of the firmware image to account for bootloader presence
Equip the application with the wolfBoot library to interact with the bootloader
Configure and compile a bootable image with a single "make" command
For help signing firmware see wolfBoot Signing
For enabling measured boot see wolfBoot measured boot

Examples provided

Additional examples available on our GitHub wolfBoot-examples repository here.

The following steps are automated in the default Makefile target, using the baremetal test application as an example to create the factory image. By running make, the build system will:

Create a Ed25519 Key-pair using the ed25519_keygen tool
Compile the bootloader. The public key generated in the step above is 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 ed25519_sign tool
Create a factory image by concatenating the bootloader and the firmware image

The factory image can be flashed to the target device. It contains the bootloader and the signed initial firmware at the specified address on the flash.

The sign.py tool transforms a bootable firmware image to comply with the firmware image format required by the bootloader.

For detailed information about the firmware image format, see Firmware image

For detailed information about the configuration options for the target system, see Compiling wolfBoot

Upgrading the firmware

Compile the new firmware image, and link it so that its entry point is at the start address of the primary partition
Sign the firmware using the sign.py 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
Trigger the image swap using libwolfboot wolfBoot_update_trigger() function. See wolfBoot library API for a description of the operation
Reboot to let the bootloader begin the image swap
Confirm the success of the update using libwolfboot wolfBoot_success() function. See wolfBoot library API for a description of the operation

For more detailed information about firmware update implementation, see Firmware Update

Additional features

Building

Git Submodules (GitHub clone only)

If you cloned wolfBoot from GitHub (rather than using a release package), you'll need to initialize and update the git submodules first:

git submodule update --init

This step is required to pull in the necessary dependencies before building.

Makefile

To build using the Makefile, create a .config file with your build specifications in the wolfBoot root directory. You can find a number of examples that you can use inside config/examples. Then run make keytools to generate the signing and key generation tools. If you have wolfCrypt-py installed and would like to use it, you can skip this step.

Documentation for the flash configuration options used in .config can be found in docs/compile.md.

For example, to build using our provided stm32h7.config:

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

CMake

See docs/CMake and cmake includes.

Troubleshooting

Python errors when signing a key:

Traceback (most recent call last):
  File "tools/keytools/keygen.py", line 135, in <module>
    rsa = ciphers.RsaPrivate.make_key(2048)
AttributeError: type object 'RsaPrivate' has no attribute 'make_key'

Traceback (most recent call last):
  File "tools/keytools/sign.py", line 189, in <module>
    r, s = ecc.sign_raw(digest)
AttributeError: 'EccPrivate' object has no attribute 'sign_raw'

You need to install the latest wolfcrypt-py here: https://github.com/wolfSSL/wolfcrypt-py

Use pip3 install wolfcrypt.

Or to install based on a local wolfSSL installation use:

cd wolfssl
./configure --enable-keygen --enable-rsa --enable-ecc --enable-ed25519 --enable-des3 CFLAGS="-DFP_MAX_BITS=8192 -DWOLFSSL_PUBLIC_MP"
make
sudo make install

cd wolfcrypt-py
USE_LOCAL_WOLFSSL=/usr/local pip3 install .

Key algorithm mismatch:

The error Key algorithm mismatch. Remove old keys via 'make keysclean' indicates the current .config SIGN algorithm does not match what is in the generated src/keystore.c file. Use make keysclean to delete keys and regenerate.

Cannot open compiler generated file ... Permission denied

This may occur due to multiple environments being opened concurrently, or anti-virus software. Try manually deleting the respective build directories and/or restarting your IDE.

sp_c32.c : fatal error C1083: Cannot open compiler generated file: '... sp_c32.obj': Permission denied

unresolved external symbol __imp____acrt_iob_fun

unresolved external symbol __imp____acrt_iob_func referenced in function _main

expected expression before ';' around WOLFBOOT_PARTITION_BOOT_ADDRESS

Search for #define WOLFBOOT_PARTITION_BOOT_ADDRESS with no value. Sometimes a failed config will generate a bad file. (typically target.h)

Rename the file with a .bak extension and let the build process generate a fresh one. Consider also deleting the entire build directory.

/src/libwolfboot.c:724:64: error: expected expression before ';' token
  724 |             address = (uint32_t)WOLFBOOT_PARTITION_BOOT_ADDRESS;

'stdint.h': No such file or directory

Check the compiler order in PREFERRED_HOST_CC_NAME_LIST, See HOST_CC in the logs.

For Visual Studio, the developer command prompt will need to be activated.

\wolfBoot\tools\keytools\sign.c(33): fatal error C1083: Cannot open include file: 'stdio.h': No such file or directory

Release Notes

v1.0 (2018-12-04)

Initial release with fail-safe update, HAL support for STM32 and nRF52

V1.1 (2019-03-27)

Added support for ECC-256 DSA
Added support for external (e.g. SPI) flash for Update/swap
Anti-rollback protection via version number
Hardware support
- Added compile options for Cortex-M0
- new HAL: Atmel SamR21
- new HAL: TI cc26x2
- new HAL: NXP/Freescale Kinetis SDK
Improved sign/update tools compatibility (windows)

V1.2 (2019-07-30)

Added support for multiple architectures
key generation and signing tools rewritten in python for portability
Added compile-time option to move flash-writing functions to RAM
Introduced the p

WolfBoot

Install / Use

README