Skip to content

Commit 1bd1ed5

Browse files
nordicjmnordicjm
committed
[nrf fromtree] doc: build: Add signing page
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 <[email protected]> (cherry picked from commit 1df0781)
1 parent dcf54a2 commit 1bd1ed5

File tree

4 files changed

+118
-131
lines changed

4 files changed

+118
-131
lines changed

‎cmake/mcuboot.cmake‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -75,17 +75,22 @@ function(zephyr_mcuboot_tasks)
7575

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

82+
if(NOT write_block_size)
83+
set(write_block_size 4)
84+
message(WARNING "slot0_partition write block size devicetree parameter is missing, assuming write block size is 4")
85+
endif()
86+
8287
# If single slot mode, or if in firmware updater mode and this is the firmware updater image,
8388
# use slot 0 information
8489
if(NOT CONFIG_MCUBOOT_BOOTLOADER_MODE_SINGLE_APP AND (NOT CONFIG_MCUBOOT_BOOTLOADER_MODE_FIRMWARE_UPDATER OR CONFIG_MCUBOOT_APPLICATION_FIRMWARE_UPDATER))
8590
# Slot 1 size is used instead of slot 0 size
8691
set(slot_size)
87-
dt_nodelabel(slot1_flash NODELABEL "slot1_partition")
88-
dt_prop(slot_size PATH "${slot1_flash}" PROPERTY "reg" INDEX 1)
92+
dt_nodelabel(slot1_flash NODELABEL "slot1_partition" REQUIRED)
93+
dt_prop(slot_size PATH "${slot1_flash}" PROPERTY "reg" INDEX 1 REQUIRED)
8994
endif()
9095

9196
# Basic 'imgtool sign' command with known image information.

‎doc/build/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ Build and Configuration Systems
1616
sysbuild/index.rst
1717
version/index.rst
1818
flashing/index.rst
19+
signing/index.rst

‎doc/build/signing/index.rst‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
.. _build-signing:
2+
3+
Signing Binaries
4+
################
5+
6+
Binaries can be optionally signed as part of a build automatically using CMake code, there is
7+
also the ability to use ``west sign`` to sign binaries too, this page describes the former, the
8+
latter is documented on :ref:`west-sign`.
9+
10+
MCUboot / imgtool
11+
*****************
12+
13+
The Zephyr build system has special support for signing binaries for use with the `MCUboot`_
14+
bootloader using the `imgtool`_ program provided by its developers. You can both build and sign
15+
this type of application binary in one step by setting some Kconfig options. If you do,
16+
``west flash`` will use the signed binaries.
17+
18+
Here 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
20+
from 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+
29+
Notes 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+
37+
For 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+
49+
If your ``west flash`` :ref:`runner <west-runner>` uses an image format supported by imgtool, you
50+
should 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+
65+
Whether ``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
67+
would like it to, please send a patch or file an issue for adding support.
68+
69+
.. _west-extending-signing:
70+
71+
Extending signing externally
72+
****************************
73+
74+
The signing script used when running ``west flash`` can be extended or replaced to change features
75+
or introduce different signing mechanisms. By default with MCUboot enabled, signing is setup by
76+
the :file:`cmake/mcuboot.cmake` file in Zephyr which adds extra post build commands for generating
77+
the signed images. The file used for signing can be replaced from a sysbuild scope (if being used)
78+
or from a zephyr/zephyr module scope, the priority of which is:
79+
80+
* Sysbuild
81+
* Zephyr property
82+
* Default MCUboot script (if enabled)
83+
84+
From sysbuild, ``-D<target>_SIGNING_SCRIPT`` can be used to set a signing script for a specific
85+
image 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+
91+
The 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+
100+
This will include the custom signing CMake file instead of the default Zephyr one when projects
101+
are built with MCUboot signing support enabled. The base Zephyr MCUboot signing file can be
102+
used 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/

‎doc/develop/west/sign.rst‎

Lines changed: 0 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -9,133 +9,6 @@ external tool. In some configurations, ``west sign`` is also used to invoke
99
an external, post-processing tool that "stitches" the final components of
1010
the image together. Run ``west sign -h`` for command line help.
1111

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

0 commit comments

Comments
 (0)