Skip to content

Commit

Permalink
doc: build: Add signing page
Browse files Browse the repository at this point in the history 
Adds a signing page under build, which contains information on
how to sign images from the build system, this removes the old
details for using west sign with imgtool from the west sign page

Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
  • Loading branch information
@nordicjm @carlescufi
nordicjm authored and carlescufi committed Oct 8, 2024
1 parent fba029c commit 1df0781
Show file tree
Hide file tree
Showing 4 changed files with 118 additions and 131 deletions.
13 changes: 9 additions & 4 deletions cmake/mcuboot.cmake
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,17 +75,22 @@ function(zephyr_mcuboot_tasks)

# Fetch devicetree details for flash and slot information
dt_chosen(flash_node PROPERTY "zephyr,flash")
dt_nodelabel(slot0_flash NODELABEL "slot0_partition")
dt_prop(slot_size PATH "${slot0_flash}" PROPERTY "reg" INDEX 1)
dt_nodelabel(slot0_flash NODELABEL "slot0_partition" REQUIRED)
dt_prop(slot_size PATH "${slot0_flash}" PROPERTY "reg" INDEX 1 REQUIRED)
dt_prop(write_block_size PATH "${flash_node}" PROPERTY "write-block-size")

if(NOT write_block_size)
set(write_block_size 4)
message(WARNING "slot0_partition write block size devicetree parameter is missing, assuming write block size is 4")
endif()

# If single slot mode, or if in firmware updater mode and this is the firmware updater image,
# use slot 0 information
if(NOT CONFIG_MCUBOOT_BOOTLOADER_MODE_SINGLE_APP AND (NOT CONFIG_MCUBOOT_BOOTLOADER_MODE_FIRMWARE_UPDATER OR CONFIG_MCUBOOT_APPLICATION_FIRMWARE_UPDATER))
# Slot 1 size is used instead of slot 0 size
set(slot_size)
dt_nodelabel(slot1_flash NODELABEL "slot1_partition")
dt_prop(slot_size PATH "${slot1_flash}" PROPERTY "reg" INDEX 1)
dt_nodelabel(slot1_flash NODELABEL "slot1_partition" REQUIRED)
dt_prop(slot_size PATH "${slot1_flash}" PROPERTY "reg" INDEX 1 REQUIRED)
endif()

# Basic 'imgtool sign' command with known image information.
Expand Down
1 change: 1 addition & 0 deletions doc/build/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,4 @@ Build and Configuration Systems
sysbuild/index.rst
version/index.rst
flashing/index.rst
signing/index.rst
108 changes: 108 additions & 0 deletions doc/build/signing/index.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
.. _build-signing:

Signing Binaries
################

Binaries can be optionally signed as part of a build automatically using CMake code, there is
also the ability to use ``west sign`` to sign binaries too, this page describes the former, the
latter is documented on :ref:`west-sign`.

MCUboot / imgtool
*****************

The Zephyr build system has special support for signing binaries for use with the `MCUboot`_
bootloader using the `imgtool`_ program provided by its developers. You can both build and sign
this type of application binary in one step by setting some Kconfig options. If you do,
``west flash`` will use the signed binaries.

Here is an example workflow, which builds and flashes MCUboot, as well as the
:zephyr:code-sample:`hello_world` application for chain-loading by MCUboot. Run these commands
from the :file:`zephyrproject` workspace you created in the :ref:`getting_started`.

.. code-block:: console
west build -b YOUR_BOARD zephyr/samples/hello_world --sysbuild -d build-hello-signed -- \
-DSB_CONFIG_BOOTLOADER_MCUBOOT=y
west flash -d build-hello-signed
Notes on the above commands:

- ``YOUR_BOARD`` should be changed to match your board
- The singing key value is the insecure default provided and used by MCUboot for development
and testing
- You can change the ``hello_world`` application directory to any other application that can be
loaded by MCUboot, such as the :zephyr:code-sample:`smp-svr` sample.

For more information on these and other related configuration options, see:

- ``SB_CONFIG_BOOTLOADER_MCUBOOT``: build the application for loading by MCUboot
- ``SB_CONFIG_BOOT_SIGNATURE_KEY_FILE``: the key file to use when singing images. If you have
your own key, change this appropriately
- :kconfig:option:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line arguments
for ``imgtool``
- :kconfig:option:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed image,
which may be more useful for flashing in production environments than the OTA-able default image
- On Windows, if you get "Access denied" issues, the recommended fix is to run
``pip3 install imgtool``, then retry with a pristine build directory.

If your ``west flash`` :ref:`runner <west-runner>` uses an image format supported by imgtool, you
should see something like this on your device's serial console when you run
``west flash -d build-hello-signed``:

.. code-block:: none
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 ***
[00:00:00.004,669] <inf> mcuboot: Starting bootloader
[00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.021,636] <inf> mcuboot: Boot source: none
[00:00:00.027,374] <inf> mcuboot: Swap type: none
[00:00:00.115,142] <inf> mcuboot: Bootloader chainload address offset: 0xc000
[00:00:00.123,168] <inf> mcuboot: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 ***
Hello World! nrf52840dk_nrf52840
Whether ``west flash`` supports this feature depends on your runner. The ``nrfjprog`` and
``pyocd`` runners work with the above flow. If your runner does not support this flow and you
would like it to, please send a patch or file an issue for adding support.

.. _west-extending-signing:

Extending signing externally
****************************

The signing script used when running ``west flash`` can be extended or replaced to change features
or introduce different signing mechanisms. By default with MCUboot enabled, signing is setup by
the :file:`cmake/mcuboot.cmake` file in Zephyr which adds extra post build commands for generating
the signed images. The file used for signing can be replaced from a sysbuild scope (if being used)
or from a zephyr/zephyr module scope, the priority of which is:

* Sysbuild
* Zephyr property
* Default MCUboot script (if enabled)

From sysbuild, ``-D<target>_SIGNING_SCRIPT`` can be used to set a signing script for a specific
image or ``-DSIGNING_SCRIPT`` can be used to set a signing script for all images, for example:

.. code-block:: console
west build -b <board> <application> -DSIGNING_SCRIPT=<file>
The zephyr property method is achieved by adjusting the ``SIGNING_SCRIPT`` property on the
``zephyr_property_target``, ideally from by a module by using:

.. code-block:: cmake
if(CONFIG_BOOTLOADER_MCUBOOT)
set_target_properties(zephyr_property_target PROPERTIES SIGNING_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/custom_signing.cmake)
endif()
This will include the custom signing CMake file instead of the default Zephyr one when projects
are built with MCUboot signing support enabled. The base Zephyr MCUboot signing file can be
used as a reference for creating a new signing system or extending the default behaviour.

.. _MCUboot:
https://mcuboot.com/

.. _imgtool:
https://pypi.org/project/imgtool/
127 changes: 0 additions & 127 deletions doc/develop/west/sign.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,133 +9,6 @@ external tool. In some configurations, ``west sign`` is also used to invoke
an external, post-processing tool that "stitches" the final components of
the image together. Run ``west sign -h`` for command line help.

MCUboot / imgtool
*****************

The Zephyr build system has special support for signing binaries for use with
the `MCUboot`_ bootloader using the `imgtool`_ program provided by its
developers. You can both build and sign this type of application binary in one
step by setting some Kconfig options. If you do, ``west flash`` will use the
signed binaries.

If you use this feature, you don't need to run ``west sign`` yourself; the
build system will do it for you.

Here is an example workflow, which builds and flashes MCUboot, as well as the
:zephyr:code-sample:`hello_world` application for chain-loading by MCUboot. Run these commands
from the :file:`zephyrproject` workspace you created in the
:ref:`getting_started`.

.. code-block:: console
west build -b YOUR_BOARD bootloader/mcuboot/boot/zephyr -d build-mcuboot
west build -b YOUR_BOARD zephyr/samples/hello_world -d build-hello-signed -- \
-DCONFIG_BOOTLOADER_MCUBOOT=y \
-DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\"
west flash -d build-mcuboot
west flash -d build-hello-signed
Notes on the above commands:

- ``YOUR_BOARD`` should be changed to match your board
- The ``CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`` value is the insecure default
provided and used by MCUboot for development and testing
- You can change the ``hello_world`` application directory to any other
application that can be loaded by MCUboot, such as the :zephyr:code-sample:`smp-svr` sample.

For more information on these and other related configuration options, see:

- :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`: build the application for loading by
MCUboot
- :kconfig:option:`CONFIG_MCUBOOT_SIGNATURE_KEY_FILE`: the key file to use with ``west
sign``. If you have your own key, change this appropriately
- :kconfig:option:`CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS`: optional additional command line
arguments for ``imgtool``
- :kconfig:option:`CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE`: also generate a confirmed
image, which may be more useful for flashing in production environments than
the OTA-able default image
- On Windows, if you get "Access denied" issues, the recommended fix is
to run ``pip3 install imgtool``, then retry with a pristine build directory.

If your ``west flash`` :ref:`runner <west-runner>` uses an image format
supported by imgtool, you should see something like this on your device's
serial console when you run ``west flash -d build-mcuboot``:

.. code-block:: none
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 ***
[00:00:00.004,669] <inf> mcuboot: Starting bootloader
[00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.021,636] <inf> mcuboot: Boot source: none
[00:00:00.027,313] <wrn> mcuboot: Failed reading image headers; Image=0
[00:00:00.035,064] <err> mcuboot: Unable to find bootable image
Then, you should see something like this when you run ``west flash -d
build-hello-signed``:

.. code-block:: none
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 ***
[00:00:00.004,669] <inf> mcuboot: Starting bootloader
[00:00:00.011,169] <inf> mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3
[00:00:00.021,636] <inf> mcuboot: Boot source: none
[00:00:00.027,374] <inf> mcuboot: Swap type: none
[00:00:00.115,142] <inf> mcuboot: Bootloader chainload address offset: 0xc000
[00:00:00.123,168] <inf> mcuboot: Jumping to the first image slot
*** Booting Zephyr OS build zephyr-v2.3.0-2310-gcebac69c8ae1 ***
Hello World! nrf52840dk_nrf52840
Whether ``west flash`` supports this feature depends on your runner. The
``nrfjprog`` and ``pyocd`` runners work with the above flow. If your runner
does not support this flow and you would like it to, please send a patch or
file an issue for adding support.

.. _west-extending-signing:

Extending signing externally
****************************

The signing script used when running ``west flash`` can be extended or replaced
to change features or introduce different signing mechanisms. By default with
MCUboot enabled, signing is setup by the :file:`cmake/mcuboot.cmake` file in
Zephyr which adds extra post build commands for generating the signed images.
The file used for signing can be replaced from a sysbuild scope (if being used)
or from a zephyr/zephyr module scope, the priority of which is:

* Sysbuild
* Zephyr property
* Default MCUboot script (if enabled)

From sysbuild, ``-D<target>_SIGNING_SCRIPT`` can be used to set a signing script
for a specific image or ``-DSIGNING_SCRIPT`` can be used to set a signing script
for all images, for example:

.. code-block:: console
west build -b <board> <application> -DSIGNING_SCRIPT=<file>
The zephyr property method is achieved by adjusting the ``SIGNING_SCRIPT`` property
on the ``zephyr_property_target``, ideally from by a module by using:

.. code-block:: cmake
if(CONFIG_BOOTLOADER_MCUBOOT)
set_target_properties(zephyr_property_target PROPERTIES SIGNING_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/custom_signing.cmake)
endif()
This will include the custom signing CMake file instead of the default Zephyr
one when projects are built with MCUboot signing support enabled. The base
Zephyr MCUboot signing file can be used as a reference for creating a new
signing system or extending the default behaviour.

.. _MCUboot:
https://mcuboot.com/

.. _imgtool:
https://pypi.org/project/imgtool/


rimage
******

Expand Down

0 comments on commit 1df0781

Please sign in to comment.