diff --git a/cmake/mcuboot.cmake b/cmake/mcuboot.cmake index 6d3708033c216a..25fa1827f33f7e 100644 --- a/cmake/mcuboot.cmake +++ b/cmake/mcuboot.cmake @@ -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. diff --git a/doc/build/index.rst b/doc/build/index.rst index 91bf4c6018c1f4..63e3bcc6dce023 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -16,3 +16,4 @@ Build and Configuration Systems sysbuild/index.rst version/index.rst flashing/index.rst + signing/index.rst diff --git a/doc/build/signing/index.rst b/doc/build/signing/index.rst new file mode 100644 index 00000000000000..03cd5fedc679e1 --- /dev/null +++ b/doc/build/signing/index.rst @@ -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 ` 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] mcuboot: Starting bootloader + [00:00:00.011,169] mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 + [00:00:00.021,636] mcuboot: Boot source: none + [00:00:00.027,374] mcuboot: Swap type: none + [00:00:00.115,142] mcuboot: Bootloader chainload address offset: 0xc000 + [00:00:00.123,168] 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_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 -DSIGNING_SCRIPT= + +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/ diff --git a/doc/develop/west/sign.rst b/doc/develop/west/sign.rst index 7de7bf7de1dd7d..9b17bf025bb10a 100644 --- a/doc/develop/west/sign.rst +++ b/doc/develop/west/sign.rst @@ -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 ` 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] mcuboot: Starting bootloader - [00:00:00.011,169] mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 - [00:00:00.021,636] mcuboot: Boot source: none - [00:00:00.027,313] mcuboot: Failed reading image headers; Image=0 - [00:00:00.035,064] 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] mcuboot: Starting bootloader - [00:00:00.011,169] mcuboot: Primary image: magic=unset, swap_type=0x1, copy_done=0x3, image_ok=0x3 - [00:00:00.021,636] mcuboot: Boot source: none - [00:00:00.027,374] mcuboot: Swap type: none - [00:00:00.115,142] mcuboot: Bootloader chainload address offset: 0xc000 - [00:00:00.123,168] 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_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 -DSIGNING_SCRIPT= - -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 ******