In this exercise, we will learn how to sign DFU images using custom keys. Only individuals with a valid key can perform a DFU on a device.
As covered in the Application verification topic. Signing a Device Firmware Update (DFU) image ensures its authenticity and integrity. A cryptographic signature is generated using a private key and attached to the DFU image. The device uses the corresponding public key to verify the signature, confirming the image is from a trusted source and has not been tampered with. The public key is automatically generated from the private key and stored in the MCUboot image.
The more observant readers might have noticed the following warning from the build logs so far:
---------------------------------------------------------
--- WARNING: Using default MCUBoot key, it should not ---
--- be used for production. ---
---------------------------------------------------------When building for MCUboot, a default signing key is used to ease development. For production, it is extremely important to use your own key instead!
MCUboot has a set of default keys, which can be found here. If we do not configure the application to use a custom key, anyone will be able to upload DFU to our device!
Using the Key Management Unit (KMU) on the nRF54L Series to store the public key
The nRF54L Series SoCs (nRF54L15, nRF54L10, nRF54L05) are equipped with a Hardware Key Management Unit (KMU) that provides:
- Safe storage for cryptographic keys
- Direct key transfer to CRACEN RAM
- Protection against unauthorized access
On the nRF54L Series, two options are available for storing the public key used to verify the signature on an image in the SoC.
- Store it in the MCUboot bootloader image itself. In this approach, the build system embeds the public key within the MCUboot bootloader image automatically
- Store it in the KMU (Recommended). Requires manual provisioning of the public key.
In this exercise, we will cover both approaches.
The tab “All other DKs” describes method 1, which, by the way, can also be done on the nRF54L Series SoCs
The tab “nRF54L15 DK” describes the KMU approach, which is only applicable to the nRF54L15 DK and is the recommended approach for the nRF54L Series devices.
Exercise steps
1. Creating the key.
You can create the key however you want; It is nothing but a normal key in .pem format. We will use the imgtool.py bundled with the nRF Connect SDK as an example.
1.1 To set our own key, we first need to generate a key. We will use imgtool for this:
python3 <NCS_PATH>/bootloader/mcuboot/scripts/imgtool.py keygen -t ecdsa-p256 -k private_key.pemUse this command if you want to store the public key using the KMU on the nRF54L Series.
Note: only ED25519 keys are supported.
python3 <NCS_PATH>/bootloader/mcuboot/scripts/imgtool.py keygen -t ed25519 -k private_key.pem 1.2 Back up the key to somewhere safe. It is not uncommon to lose the key and thus be unable to ever do DFU on the devices again.
2. Configure the project to use this key.
Next up, we will configure the project to use this key. The key is used both by MCUboot to generate a custom key, and by Sysbuild to automatically create and sign DFU files. Therefore, this is set in Sysbuild Kconfig.
2.1 To configure our project to use this key, we will follow docs at Bootloader & DFU -> Signature keys. We set the path to the key in sysbuild.conf. We can use the full path of the key if it is stored elsewhere on the PC, but for this example, the key is stored in the project folder, and we will use ${APP_DIR}:
# STEP 2.1 - Add private key for MCUboot
SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="\${APP_DIR}/private_key.pem"2.2 Next, we should configure the key type to match the key we generated in step 1.1.
# STEP 2.2. - Configure key type
SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=yOn the nRF54L15 DK, we need to enable the following two parameters:
SB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU – This option enables using Key Management Unit (KMU) to store keys for signature verification instead of compiling key data into the MCUboot bootloader image. Using KMU requires manually provisioning the public key, which is done in the next step.
The SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519 is to select the type of key.
# STEP 2.2. - Configure key type
SB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU=y
SB_CONFIG_BOOT_SIGNATURE_TYPE_ED25519=y2.3 (nRF54L15 DK only) Provision the public key to the device.
This step is only applicable to the nRF54L15 DK. Skip this step if you are using other DKs.
No action is needed here. The public key will be stored in the MCUboot bootloader image automatically by the build system
If you are using the KMU to store the public key (Only applicable for the nRF54L15 Series ). You need to upload the public key to the device; the build system does NOT do this automatically at this stage, and it needs to be done manually. The nRF Connect SDK provides a west command, ncs-provision, allowing the upload of keys to the device through the Serial Write Debug (SWD) interface.
west ncs-provision upload -s nrf54l15 -k private_key.pemYou should expect an output similar to this :
2025-02-18 14:05:29,955 INFO nrfprovision.py:520 [main ] : Provision of keyslot executed, id = 226
2025-02-18 14:05:29,955 INFO nrfprovision.py:411 [verify_pubkey ] : Verify keyslot through readback of push destination address
2025-02-18 14:05:29,970 INFO nrfprovision.py:420 [verify_pubkey ] : Asymmetric key sucsessfully provisionedFor more information about provisioning on the nRF54L Series, you can read Performing KMU provisioning
3. Build the project again.
- Build (pristine build) the project and flash it normally.
During this step, you can observe that the warning about the missing key is gone and build logs lists that we are using our key.
MCUBoot bootloader key file: <PATH>/ncs-inter/v2.9.0-v2.7.0/l9/l9_e2/private_key.pem- Change led blinking period and build (do not flash)
- Use AuTerm to upload a new DFU image
- Reset the board
Recall
These steps were described in details in Exercise 1 – DFU over UART, steps 5.3 and 5.4.
4. Check that it fails with the wrong key.
Lastly, checking that it fails with the wrong key is a good idea.
4.1 Generate a new custom key. Save this key as a different file to avoid losing the correct one.
python3 <NCS_PATH>/bootloader/mcuboot/scripts/imgtool.py keygen -t ecdsa-p256 -k do_not_use_this_key.pempython3 <NCS_PATH>/bootloader/mcuboot/scripts/imgtool.py keygen -t ed25519 -k do_not_use_this_key.pemNext, update sysbuild configuration to use the newly generated key.
SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="\${APP_DIR}/do_not_use_this_key.pem"4.2 Now, try to do DFU over UART as we learned in Exercise 1 (sections: 5.3 – 5.4) with the new zephyr.signed.bin. Since this one uses a different key than the one we flashed in step 3 , DFU should fail with the error (remember to close AuTerm before connecting serial terminal in VSCode and resetting the board):
5. Update the board again by changing the key.
It is possible to update the board again by changing the key to the proper one and doing a pristine build (this will cause signing the firmware again with the correct key).
SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="\${APP_DIR}/private_key.pem"