1.. _west-sign:
2
3Signing Binaries
4################
5
6The ``west sign`` :ref:`extension <west-extensions>` command can be used to
7sign a Zephyr application binary for consumption by a bootloader using an
8external tool. In some configurations, ``west sign`` is also used to invoke
9an external, post-processing tool that "stitches" the final components of
10the image together. Run ``west sign -h`` for command line help.
11
12rimage
13******
14
15rimage configuration uses an approach that does not rely on Kconfig or CMake
16but on :ref:`west config<west-config>`, similar to
17:ref:`west-building-cmake-config`.
18
19Signing involves a number of "wrapper" scripts stacked on top of each other: ``west
20flash`` invokes ``west build`` which invokes ``cmake`` and ``ninja`` which invokes
21``west sign`` which invokes ``imgtool`` or `rimage`_. As long as the signing
22parameters desired are the default ones and fairly static, these indirections are
23not a problem. On the other hand, passing ``imgtool`` or ``rimage`` options through
24all these layers can causes issues typical when the layers don't abstract
25anything. First, this usually requires boilerplate code in each layer. Quoting
26whitespace or other special characters through all the wrappers can be
27difficult. Reproducing a lower ``west sign`` command to debug some build-time issue
28can be very time-consuming: it requires at least enabling and searching verbose
29build logs to find which exact options were used. Copying these options from the
30build logs can be unreliable: it may produce different results because of subtle
31environment differences. Last and worst: new signing feature and options are
32impossible to use until more boilerplate code has been added in each layer.
33
34To avoid these issues, ``rimage`` parameters can bet set in ``west config``.
35Here's a ``workspace/.west/config`` example:
36
37.. code-block:: ini
38
39   [sign]
40   # Not needed when invoked from CMake
41   tool = rimage
42
43   [rimage]
44   # Quoting is optional and works like in Unix shells
45   # Not needed when rimage can be found in the default PATH
46   path = "/home/me/zworkspace/build-rimage/rimage"
47
48   # Not needed when using the default development key
49   extra-args = -i 4 -k 'keys/key argument with space.pem'
50
51In order to support quoting, values are parsed by Python's ``shlex.split()`` like in
52:ref:`west-building-cmake-args`.
53
54The ``extra-args`` are passed directly to the ``rimage`` command. The example
55above has the same effect as appending them on command line after ``--`` like this:
56``west sign --tool rimage -- -i 4 -k 'keys/key argument with space.pem'``. In case
57both are used, the command-line arguments go last.
58
59.. _rimage:
60   https://github.com/thesofproject/rimage
61