1.. _build-signing: 2 3Signing Binaries 4################ 5 6Binaries can be optionally signed as part of a build automatically using CMake code, there is 7also the ability to use ``west sign`` to sign binaries too, this page describes the former, the 8latter is documented on :ref:`west-sign`. 9 10MCUboot / imgtool 11***************** 12 13The Zephyr build system has special support for signing binaries for use with the `MCUboot`_ 14bootloader using the `imgtool`_ program provided by its developers. You can both build and sign 15this type of application binary in one step by setting some Kconfig options. If you do, 16``west flash`` will use the signed binaries. 17 18Here is an example workflow, which builds and flashes MCUboot, as well as the 19:zephyr:code-sample:`hello_world` application for chain-loading by MCUboot. Run these commands 20from the :file:`zephyrproject` workspace you created in the :ref:`getting_started`. 21 22.. code-block:: console 23 24 west build -b YOUR_BOARD zephyr/samples/hello_world --sysbuild -d build-hello-signed -- \ 25 -DSB_CONFIG_BOOTLOADER_MCUBOOT=y 26 27 west flash -d build-hello-signed 28 29Notes on the above commands: 30 31- ``YOUR_BOARD`` should be changed to match your board 32- The singing key value is the insecure default provided and used by MCUboot for development 33 and testing 34- You can change the ``hello_world`` application directory to any other application that can be 35 loaded by MCUboot, such as the :zephyr:code-sample:`smp-svr` sample. 36 37For more information on these and other related configuration options, see: 38 39- ``SB_CONFIG_BOOTLOADER_MCUBOOT``: build the application for loading by MCUboot 40- ``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE``: the key file to use when singing images. If you have 41 your own key, change this appropriately 42- :kconfig:option:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line arguments 43 for ``imgtool`` 44- :kconfig:option:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed image, 45 which may be more useful for flashing in production environments than the OTA-able default image 46- On Windows, if you get "Access denied" issues, the recommended fix is to run 47 ``pip3 install imgtool``, then retry with a pristine build directory. 48 49If your ``west flash`` :ref:`runner <west-runner>` uses an image format supported by imgtool, you 50should see something like this on your device's serial console when you run 51``west flash -d build-hello-signed``: 52 53.. code-block:: none 54 55 *** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 *** 56 [00:00:00.004,669] <inf> mcuboot: Starting bootloader 57 [00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 58 [00:00:00.021,636] <inf> mcuboot: Boot source: none 59 [00:00:00.027,374] <inf> mcuboot: Swap type: none 60 [00:00:00.115,142] <inf> mcuboot: Bootloader chainload address offset: 0xc000 61 [00:00:00.123,168] <inf> mcuboot: Jumping to the first image slot 62 *** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 *** 63 Hello World! nrf52840dk_nrf52840 64 65Whether ``west flash`` supports this feature depends on your runner. The ``nrfjprog`` and 66``pyocd`` runners work with the above flow. If your runner does not support this flow and you 67would like it to, please send a patch or file an issue for adding support. 68 69.. _west-extending-signing: 70 71Extending signing externally 72**************************** 73 74The signing script used when running ``west flash`` can be extended or replaced to change features 75or introduce different signing mechanisms. By default with MCUboot enabled, signing is setup by 76the :file:`cmake/mcuboot.cmake` file in Zephyr which adds extra post build commands for generating 77the signed images. The file used for signing can be replaced from a sysbuild scope (if being used) 78or from a zephyr/zephyr module scope, the priority of which is: 79 80* Sysbuild 81* Zephyr property 82* Default MCUboot script (if enabled) 83 84From sysbuild, ``-D<target>_SIGNING_SCRIPT`` can be used to set a signing script for a specific 85image or ``-DSIGNING_SCRIPT`` can be used to set a signing script for all images, for example: 86 87.. code-block:: console 88 89 west build -b <board> <application> -DSIGNING_SCRIPT=<file> 90 91The zephyr property method is achieved by adjusting the ``SIGNING_SCRIPT`` property on the 92``zephyr_property_target``, ideally from by a module by using: 93 94.. code-block:: cmake 95 96 if(CONFIG_BOOTLOADER_MCUBOOT) 97 set_target_properties(zephyr_property_target PROPERTIES SIGNING_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/custom_signing.cmake) 98 endif() 99 100This will include the custom signing CMake file instead of the default Zephyr one when projects 101are built with MCUboot signing support enabled. The base Zephyr MCUboot signing file can be 102used as a reference for creating a new signing system or extending the default behaviour. 103 104.. _MCUboot: 105 https://mcuboot.com/ 106 107.. _imgtool: 108 https://pypi.org/project/imgtool/ 109
