.. _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/