Signing Binaries

The west sign extension command can be used to sign a Zephyr application binary for consumption by a bootloader using an external tool. Run west sign -h for command line help.

MCUboot / imgtool

The Zephyr build system has special support for signing binaries for use with the MCUboot bootloader using the imgtool program provided by its developers. You can both build and sign this type of application binary in one step by setting some Kconfig options. If you do, west flash will use the signed binaries.

If you use this feature, you don’t need to run west sign yourself; the build system will do it for you.

Here is an example workflow, which builds and flashes MCUboot, as well as the Hello World application for chain-loading by MCUboot. Run these commands from the zephyrproject workspace you created in the Getting Started Guide.

west build -b YOUR_BOARD -s bootloader/mcuboot/boot/zephyr -d build-mcuboot
west build -b YOUR_BOARD -s zephyr/samples/hello_world -d build-hello-signed -- \
     -DCONFIG_BOOTLOADER_MCUBOOT=y \
     -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"

west flash -d build-mcuboot
west flash -d build-hello-signed

Notes on the above commands:

YOUR_BOARD should be changed to match your board
The CONFIG_MCUBOOT_SIGNATURE_KEY_FILE value is the insecure default provided and used by by MCUboot for development and testing
You can change the hello_world application directory to any other application that can be loaded by MCUboot, such as the SMP Server Sample

For more information on these and other related configuration options, see:

CONFIG_BOOTLOADER_MCUBOOT: build the application for loading by MCUboot
CONFIG_MCUBOOT_SIGNATURE_KEY_FILE: the key file to use with west sign. If you have your own key, change this appropriately
CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS: optional additional command line arguments for imgtool
CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE: also generate a confirmed image, which may be more useful for flashing in production environments than the OTA-able default image
On Windows, if you get “Access denied” issues, the recommended fix is to run pip3 install imgtool, then retry with a pristine build directory.

If your west flash runner uses an image format supported by imgtool, you should see something like this on your device’s serial console when you run west flash -d build-mcuboot:

*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1  ***
[00:00:00.004,669] <inf> mcuboot: Starting bootloader
[00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.021,636] <inf> mcuboot: Boot source: none
[00:00:00.027,313] <wrn> mcuboot: Failed reading image headers; Image=0
[00:00:00.035,064] <err> mcuboot: Unable to find bootable image

Then, you should see something like this when you run west flash -d build-hello-signed:

*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1  ***
[00:00:00.004,669] <inf> mcuboot: Starting bootloader
[00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.021,636] <inf> mcuboot: Boot source: none
[00:00:00.027,374] <inf> mcuboot: Swap type: none
[00:00:00.115,142] <inf> mcuboot: Bootloader chainload address offset: 0xc000
[00:00:00.123,168] <inf> mcuboot: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1  ***
Hello World! nrf52840dk_nrf52840

Whether west flash supports this feature depends on your runner. The nrfjprog and pyocd runners work with the above flow. If your runner does not support this flow and you would like it to, please send a patch or file an issue for adding support.