Skip to content

Commit e61f950

Browse files
FrancescoSercarlescufi
FrancescoSer
authored and
carlescufi
committed
doc: Added 54H dfu MCUboot userguide
Added 54H dfu MCUboot userguide Signed-off-by: Francesco Domenico Servidio <[email protected]>
1 parent c11cd3d commit e61f950

File tree

4 files changed

+254
-0
lines changed

4 files changed

+254
-0
lines changed

‎doc/nrf/app_dev/device_guides/nrf54h/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,5 @@ Zephyr and the |NCS| provide support and contain board definitions for developin
4242
ug_nrf54h20_flpr
4343
ug_nrf54h20_ppr
4444
../nrf54l/zms.rst
45+
ug_nrf54h20_mcuboot_dfu
46+
ug_nrf54h_ecies_x25519

‎doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h20_mcuboot_dfu.rst‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
.. _ug_nrf54h20_mcuboot_dfu:
2+
3+
Configuring DFU and MCUboot
4+
###########################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
This page provides an overview of Device Firmware Update (DFU) for the nRF54H Series devices, detailing the necessary steps, configurations, and potential risks involved in setting up secure boot and firmware updates.
11+
12+
On the nRF54H20 SoC, you can use MCUboot as a *standalone immutable bootloader*.
13+
If you want to learn how to start using MCUboot in your application, refer to the :ref:`ug_bootloader_adding_sysbuild` page.
14+
For full introduction to the bootloader and DFU solution, see :ref:`ug_bootloader_mcuboot_nsib` and :ref:`ug_bootloader_adding_sysbuild_immutable_mcuboot`.
15+
16+
.. note::
17+
|NSIB| is not supported on the nRF54H20 SoC.
18+
19+
You must select a sample that supports DFU to ensure proper testing of its functionality.
20+
In the following sections, the SMP server sample variant in the :file:`samples/zephyr/subsys/mgmt/mcumgr/smp_svr` folder is used.
21+
It extends the Zephyr's :zephyr:code-sample:`smp-svr` sample and adapts it for nRF54H20 platform.
22+
23+
.. note::
24+
There are two variants of the SMP server sample:
25+
26+
* The new ``sdk-nrf`` sample supporting the nRF54H20 SoC, located in the :file:`samples/zephyr/subsys/mgmt/mcumgr/smp_svr` folder.
27+
* The :zephyr:code-sample:`smp-svr`, located in the :file:`samples/subsys/mgmt/mcumgr/smp_svr` folder, is the Zephyr sample that supports MCUboot and DFU.
28+
29+
Configuring MCUboot on the nRF54H20 DK
30+
**************************************
31+
32+
You can build any nRF54H20 SoC sample with MCUboot support by passing the :kconfig:option:`SB_CONFIG_BOOTLOADER_MCUBOOT` Kconfig option.
33+
This enables the default *swap using move* bootloader mode, supports a single updateable image, and applies the standard MCUboot configurations.
34+
35+
To configure the :zephyr:code-sample:`hello_world` sample for using MCUboot, follow these steps:
36+
37+
1. Navigate to the :file:`zephyr/samples/hello_world` directory.
38+
39+
#. Build the firmware:
40+
41+
.. parsed-literal::
42+
:class: highlight
43+
44+
west build -b nrf54h20dk/nrf54h20/cpuapp -p -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y
45+
46+
#. Program the firmware onto the device:
47+
48+
.. parsed-literal::
49+
:class: highlight
50+
51+
west flash
52+
53+
See the :zephyr:code-sample:`smp-svr` sample for a reference of how you can further configure your application with MCUboot.
54+
It demonstrates how to enable :ref:`dfu_tools_mcumgr_cli` commands in the application, allowing you to read information about images managed by MCUboot.
55+
56+
RAM cleanup
57+
***********
58+
59+
60+
To prevent data leakage, enable MCUboot's RAM cleanup by setting the :kconfig:option:`SB_CLEANUP_RAM` Kconfig option as follows:
61+
62+
* When building with CMake, add ``-Dmcuboot_CONFIG_SB_CLEANUP_RAM``.
63+
* When using sysbuild, add ``CONFIG_SB_CLEANUP_RAM=y`` to :file:`sysbuild/mcuboot.conf`.
64+
65+
This feature is controlled by the :kconfig:option:`CONFIG_SB_CLEANUP_RAM` Kconfig option.
66+
67+
Supported signatures
68+
********************
69+
70+
MCUboot supports the following signature types:
71+
72+
* Ed25519 - default for nRF54H20
73+
* ECDSA P256 - enabled by setting :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256` to ``y``
74+
75+
By default, MCUboot stores the public key in its own bootloader image.
76+
The build system automatically embeds the key at compile time.
77+
For more information, see `DFU with custom keys`_.
78+
79+
Image encryption
80+
****************
81+
82+
MCUboot supports AES-encrypted images on the nRF54H20 SoC, using ECIES-X25519 for key exchange.
83+
For detailed information on ECIES-X25519 support, refer to the :ref:`ug_nrf54h_ecies_x25519` documentation page.
84+
85+
.. warning::
86+
On the nRF54H20 SoC, private and public keys are currently stored in the image.
87+
Embedding keys directly within the firmware image could pose a potential security risk.
88+
89+
DFU configuration example
90+
*************************
91+
92+
MCUboot supports various methods for updating firmware images.
93+
On the nRF54H platform, you can use :ref:`swap and direct-xip modes<ug_bootloader_main_config>`.
94+
95+
For more information, see the :file:`samples/zephyr/subsys/mgmt/mcumgr/smp_svr` sample.
96+
This sample demonstrates how to configure DFU feature in both MCUBoot and user application in your project.
97+
It uses Simple Management Protocol for DFU and querying device information from the application.
98+
99+
The following build flavours are available:
100+
101+
* ``sample.mcumgr.smp_svr.bt.nrf54h20dk`` - DFU over BLE using the default :ref:`ipc_radio` image and *Swap using move* MCUboot mode.
102+
* ``sample.mcumgr.smp_svr.bt.nrf54h20dk.direct_xip_withrevert`` - DFU over BLE using *Direct-XIP with revert* MCUboot mode.
103+
* ``sample.mcumgr.smp_svr.serial.nrf54h20dk.ecdsa`` - DFU over serial port with ECDSA P256 signature verification.
104+
105+
To build and run the sample, use the following commands:
106+
107+
.. code-block:: console
108+
109+
west build -b nrf54h20dk/nrf54h20/cpuapp -T ./sample.mcumgr.smp_svr.bt.nrf54h20dk
110+
west flash
111+
112+
Testing steps
113+
=============
114+
115+
You can test the :zephyr:code-sample:`smp-svr` sample by performing a FOTA update.
116+
To do so, complete the following steps:
117+
118+
1. Locate the :file:`dfu_application.zip` archive in the build directory of the build from the previous chapter.
119+
The archive is automatically generated after adding the DFU configuration and building your project.
120+
121+
.. note::
122+
For each image included in the DFU-generated package, use a higher version number than your currently active firmware.
123+
You can do this by modifying the VERSION file in the application directory or by making changes to the application code.
124+
For the semantic versioning, modify the :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` Kconfig option.
125+
Otherwise, the DFU target may reject the FOTA process due to a downgrade prevention mechanism.
126+
127+
#. Download the :file:`dfu_application.zip` archive to your mobile phone.
128+
See :ref:`app_build_output_files` for more information about the contents of update archive.
129+
130+
.. note::
131+
nRF Connect for Desktop does not currently support the FOTA process.
132+
133+
#. Use the `nRF Connect Device Manager`_ mobile app to update your device with the new firmware.
134+
135+
a. Ensure that you can access the :file:`dfu_application.zip` archive from your phone or tablet.
136+
#. In the mobile app, scan and select the device to update.
137+
#. Switch to the :guilabel:`Image` tab.
138+
#. Tap the :guilabel:`SELECT FILE` button and select the :file:`dfu_application.zip` archive.
139+
#. Tap the :guilabel:`START` button.
140+
#. Initiate the DFU process of transferring the image to the device:
141+
142+
* If you are using an Android phone or tablet, select a mode in the dialog window, and tap the :guilabel:`START` button.
143+
* If you are using an iOS device, tap the selected mode in the pop-up window.
144+
145+
.. note::
146+
For samples using random HCI identities, the Test and Confirm mode should not be used.
147+
148+
#. Wait for the DFU to finish and then verify that the new application works properly by observing the new device name visible in the Device Manager app.
149+
150+
151+
Additional Information
152+
**********************
153+
154+
You can test BLE-based FOTA samples with the `nRF Connect Device Manager`_.
155+
For DFU over a serial connection, use the :ref:`dfu_tools_mcumgr_cli` tool.
156+
157+
.. note::
158+
On the nRF54H20 SoC, Direct XIP mode uses a merged image slot that combines both application and radio core images.
159+
Refer to the sample's DTS overlay files to understand the partition layout.
160+
In contrast, Swap modes place application and radio images in separate MCUboot slots, enabling multi-image updates.
161+
162+
Direct XIP (merged) build artifacts are generated in ``build/zephyr``.
163+
Swap-mode artifacts reside in subdirectories under ``build`` (for example, ``build/smp_svr/zephyr`` or ``build/ipc_radio/zephyr``).
164+
165+
.. note::
166+
DFU from external flash is currently not supported on the nRF54H20 SoC.

‎doc/nrf/app_dev/device_guides/nrf54h/ug_nrf54h_ecies_x25519.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
.. _ug_nrf54h_ecies_x25519:
2+
3+
MCUboot AES image encryption with ECIES-X25519 key exchange
4+
###########################################################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
MCUboot on the nRF54H20 SoC can support encrypted images using AES.
11+
Images are encrypted using AES, and ECIES-X25519 is used for key delivery (exchange) within the image.
12+
When image encryption is enabled, you can choose to upload signed or encrypted images to be swapped during boot.
13+
If MCUboot finds an encrypted image in the secondary slot, it decrypts the image during the slot swapping process.
14+
An image that was encrypted before being swapped into the primary slot is re-encrypted if the swap is later reverted.
15+
16+
Limitations
17+
***********
18+
19+
The current implementation has the following limitations:
20+
21+
* On the nRF54H20 SoC,ECIES-X25519 key exchange requires the ED25519 signature algorithm (default).
22+
* Encryption is not supported when using MCUboot in direct-xip mode.
23+
* HMAC and HKDF tools currently use the SHA-256 hash algorithm.
24+
25+
.. note::
26+
In the |NCS| v3.1.0, encryption is supported only through the TinyCrypt library.
27+
PSA Crypto is not yet supported (known issue NCSDK-34745).
28+
As a workaround, disable :kconfig:option:`CONFIG_NRF_SECURITY` if encryption is required.
29+
30+
HMAC and HKDF impact on TLV and key exchange
31+
********************************************
32+
33+
An encrypted image includes a TLV that contains the public key for ECIES-X25519 key exchange, the encrypted AES key, and the MAC tag of the encrypted key.
34+
The key used to encrypt the AES key is derived using HKDF, and the MAC tag is generated using HMAC.
35+
36+
While the use of SHA-256 does not pose a security concern and has a minimal impact on performance, it increases the code size.
37+
This is because SHA-256 support must be included in addition to SHA-512, which is already used by the ED25519 signature algorithm.
38+
39+
Additionally, pre-installed MCUboot instances will not be able to boot images that use TLVs generated with different hash algorithms.
40+
41+
Building application with image encryption
42+
******************************************
43+
44+
To build an application that uses MCUboot with image encryption enabled, run the following command:
45+
46+
.. parsed-literal::
47+
:class: highlight
48+
49+
west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_BOOT_ENCRYPTION=y
50+
51+
The :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION` option enables encryption support in MCUboot.
52+
53+
The key exchange method is determined by the type of signature key selected.
54+
For the nRF54H20 SoC, the ED25519 signature algorithm is the default setting.
55+
56+
When encryption is enabled, the encrypted image files :file:`zephyr.signed.encrypted.bin` and :file:`zephyr.signed.encrypted.hex` are generated in the application build directory.
57+
58+
The BIN file is a binary image suitable for Device Firmware Update (DFU) operations using :ref:`MCUmgr<dfu_tools_mcumgr_cli>`.
59+
60+
When the :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE` option is enabled, you must provide an ECIES-X25519 private key in PEM format.
61+
This key is built into the MCUboot image during the build process.
62+
See the following example:
63+
64+
.. parsed-literal::
65+
:class: highlight
66+
67+
west build -b *board_target* -- -DSB_CONFIG_BOOTLOADER_MCUBOOT=y -DSB_CONFIG_BOOT_ENCRYPTION=y -DSB_CONFIG_BOOT_ENCRYPTION_KEY_FILE=\"<path to key.pem>\"
68+
69+
.. note::
70+
* The public key, derived from the specified private key file, is added to the image and later used on the device to derive the decryption key for the application image.
71+
This public key is automatically derived from the private key by imgtool, which is invoked by the build system when signing the image.
72+
* The sysbuild option :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION` sets the MCUboot configuration option :kconfig:option:`CONFIG_BOOT_ENCRYPT_IMAGE`.
73+
Similarly, the :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE` option sets both :kconfig:option:`CONFIG_BOOT_ENCRYPTION_KEY_FILE` for MCUboot and :kconfig:option:`CONFIG_MCUBOOT_ENCRYPTION_KEY_FILE` for the default application.
74+
75+
These values are then passed to imgtool for encrypting the application image.
76+
77+
You cannot override these options using MCUboot or application-level Kconfig options, as they are enforced by sysbuild.
78+
79+
Enabling encryption in |nRFVSC| projects
80+
****************************************
81+
82+
To correctly set up encryption in |nRFVSC|, you must familiarize yourself with `How to work with build configurations`_.
83+
When configuring build options, ensure to include :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION` and :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE` Kconfig options using extra CMake arguments.
84+
85+
If you are modifying an existing project, you must regenerate it to activate new settings.

‎doc/nrf/links.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1887,3 +1887,4 @@
18871887
.. _`clocks devicetree macro API`: https://github.com/nrfconnect/sdk-zephyr/blob/main/include/zephyr/devicetree/clocks.h
18881888

18891889
.. _`nRF54H20 DK memory map`: https://github.com/nrfconnect/sdk-zephyr/blob/main/boards/nordic/nrf54h20dk/nrf54h20dk_nrf54h20-memory_map.dtsi
1890+
.. _`DFU with custom keys`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-intermediate/lessons/lesson-9-bootloaders-and-dfu-fota/topic/exercise-2-dfu-over-usb-adding-external-flash

0 commit comments

Comments
 (0)