The latest development version of this page may be more current than this released 2.3.0 version.

Signing Binaries

This page documents the west sign extension command included in the zephyr repository. It is used to sign a Zephyr application binary for consumption by a bootloader using an external tool.

Currently, it supports signing binaries for use with the MCUboot bootloader, using the imgtool program provided by its developers. Using west sign as a wrapper around imgtool for Zephyr binaries is more convenient than using imgtool directly, because west sign knows how to read numeric values needed by imgtool out of an application build directory. These values differ depending on your board, so using west sign means both shorter command lines and not having to learn or memorize hardware-specific details.

To produce signed .bin and .hex files for a Zephyr application, make sure imgtool is installed (e.g. with pip3 install imgtool on macOS and Windows, and pip3 install --user imgtool on Linux), then run:

west sign -t imgtool -d YOUR_BUILD_DIR -- --key YOUR_SIGNING_KEY.pem

Above, YOUR_BUILD_DIR is a Zephyr build directory containing an application compiled for MCUboot (in practice, this means CONFIG_BOOTLOADER_MCUBOOT is y in the application’s Kconfig).

Some additional notes follow. See west sign -h for detailed help.

  • The default -d value is build, which is the default output directory created by west build.

  • If you don’t have your own signing key and have a default MCUboot build, use --key path/to/mcuboot/root-rsa-2048.pem.

  • By default, the output files produced by west sign are named zephyr.signed.bin and zephyr.signed.hex and are created in the build directory next to the unsigned zephyr.bin and zephyr.hex versions.

    You can control this using the -B and -H options, e.g. this would create my-signed.bin and my-signed.hex in the current working directory instead:

    west sign -t imgtool -B my-signed.bin -H my-signed.hex [...]

Example build flow

For reference, here is an example showing how to build Hello World for MCUboot using west:

west build -b YOUR_BOARD samples/hello_world -- -DCONFIG_BOOTLOADER_MCUBOOT=y
west sign -t imgtool -- --key YOUR_SIGNING_KEY.pem
west flash --hex-file build/zephyr/zephyr.signed.hex

The availability of a hex file, and whether west flash uses it to flash, depends on your board and build configuration. At least the west flash runners using nrfjprog and pyocd work with the above flow.