71 lines
2.8 KiB
ReStructuredText
71 lines
2.8 KiB
ReStructuredText
.. _west-sign:
|
|
|
|
Signing Binaries
|
|
################
|
|
|
|
This page documents the ``west sign`` :ref:`extension <west-extensions>`
|
|
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 :ref:`board <boards>`, 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:
|
|
|
|
.. code-block:: console
|
|
|
|
west sign -t imgtool -d YOUR_BUILD_DIR -- --key YOUR_SIGNING_KEY.pem
|
|
|
|
Above, :file:`YOUR_BUILD_DIR` is a Zephyr build directory containing an
|
|
application compiled for MCUboot (in practice, this means
|
|
:option:`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 :ref:`west build <west-building>`.
|
|
- 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
|
|
:file:`zephyr.signed.bin` and :file:`zephyr.signed.hex` and are created in the
|
|
build directory next to the unsigned :file:`zephyr.bin` and :file:`zephyr.hex`
|
|
versions.
|
|
|
|
You can control this using the ``-B`` and ``-H`` options, e.g. this would
|
|
create :file:`my-signed.bin` and :file:`my-signed.hex` in the current working
|
|
directory instead:
|
|
|
|
.. code-block:: console
|
|
|
|
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 :ref:`hello_world` for
|
|
MCUboot using ``west``:
|
|
|
|
.. code-block:: console
|
|
|
|
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.
|
|
|
|
.. _MCUboot:
|
|
https://mcuboot.com/
|
|
|
|
.. _imgtool:
|
|
https://pypi.org/project/imgtool/
|