nRF5 SDK v15.0.0
Validation

Before a Device Firmware Update is carried out, the new image should be validated. Some information (for example, the compatibility) can be checked before the actual firmware is transferred (prevalidation). Other information, for example the hash of the image, should be validated after the transfer (postvalidation).

The provided firmware package must include the firmware image and an init packet that can be used to prevalidate the image. The format of the init packet and the actual validation process is defined by the DFU bootloader implementation. See Init packet for documentation about the validation that is used in the BLE Secure DFU Bootloader example.

To be compatible, the validation (which is part of the DFU bootloader implementation) and the image creation (usually done with an external tool) must use the same init packet format. A convenient way of ensuring the common format is to define the required contents of the init packet in a protocol buffer file. In this way, the packet format can be defined once and then be used in different places. See the BLE Secure DFU Bootloader example for an example implementation.

Init packet

When performing a DFU, you must provide a package (in zip format) that contains the firmware image, an init packet, and a manifest file that indicates the package format. The init packet contains information about the firmware image that is used to validate the image, and it must be signed to ensure that the update comes from a trusted source.

Nordic provides the command line tool nrfutil to create firmware packages with an init packet in a format defined by a protocol buffer file. See Creating a firmware package with nrfutil for information about how to use nrfutil to create a firmware package that is compatible with the BLE Secure DFU Bootloader example. If you change the format of the init packet in your DFU bootloader implementation, see the nrfutil documentation for instructions on how to update the tool. Alternatively, you can create your own tool to create the firmware package.

The required contents of the init packet are defined in the protocol buffer file dfu-cc.proto. The following fields of the init packet are checked during the validation of the init packet:

Type Field name Description
Type of the image type The image can be an application image, SoftDevice image, bootloader image, or a combined image of bootloader and SoftDevice.
Hash of the image hash The hash consists of two fields: an integer that specifies the used hash function and a byte array that contains the hash of the complete package.
Firmware version fw_version This integer represents the firmware version of either the bootloader or the application image in the package. (The SoftDevice version is specified in a separate field.)
Hardware version hw_version This integer represents the required hardware version of the device.
Allowed versions of the SoftDevice sd_req[] This array of integers represents what SoftDevice firmware IDs are accepted for the image. Up to 16 allowed SoftDevice versions may be specified.
Size of the new SoftDevice, bootloader, or application sd_size, bl_size, app_size These integer values specify the size of the SoftDevice, bootloader, or application.
Signature type signature_type The type of signature that the init packet is signed with. The DFU code supports ECDSA_P256_SHA256 out of the box.
Signature signature See Cryptography library - nrf_crypto for more information.
Debugging is_debug When this flag is set, version validation (see Validation) is skipped. This flag is only honored in the debug projects. The non-debug projects always validate versions.

Creating a firmware package with nrfutil

To create a zip file that contains the firmware image (or images) and the corresponding init packet, use the nrfutil tool (version 2.2.0 or later). This tool is available as a standalone Python package from the Nordic Semiconductor nrfutil GitHub repository or can be installed from pypi with pip install nrfutil. See the nrfutil documentation for more information. Run nrfutil pkg generate --help to display help about creating a zip file.

You can add the following firmware images in binary or hexadecimal format to the zip file:

You can also combine several images in one zip file. Note that, depending on the combination of images, the created zip file might contain two firmware packages (one for the bootloader and/or SoftDevice and one for the application) and the DFU process will be carried out in two steps. If you include both a bootloader and a SoftDevice in your firmware package, those two images will be merged together. An application, however, will always be updated separately after the other updates are completed.

In addition to the images, specify the information that you want to add to the init packet. The following options are available:

Option Example value Description
--debug-mode n/a Add this flag to skip version validation.
--key-file file c:\vault\priv.pemA private (signing) key in PEM format that is used to cryptographically sign the firmware image (see Working with keys).
--application-version version 0xff The version of the application image.
--bootloader-version version 0xff The version of the bootloader image.
--hw-version version 52 The version of the hardware that should accept the image.
--sd-req sd_list 0x87,0x8C,0xA7,0xA8,0xA9A comma-separated list of FWID values of installed, on-target SoftDevices that are valid to be used with the new image. Run nrfutil pkg generate --help to display a list of possible values.

For SD + BL + App updates, remember to also specify the --sd-id field.

See the nrfutil documentation for additional information about nrfutil and about the required steps if you want to customize the init packet.

Validation

Validation of the image includes checks to verify that the image originates from a trusted source and that it is compatible with the device and the current firmware and hardware. If the flag is_debug is set in the init packet, the debug version of the example skips version validation.

These checks are implemented in the Validation module. Verification is done in the following order:

  1. Signature of the packet, signature. To be able to verify the signature, the validation code needs the public key that corresponds to the private key that was used to sign the init packet. This key is located in the file dfu_public_key.c. The signature verification can be enabled/disabled with the NRF_DFU_REQUIRE_SIGNED_APP_UPDATE config. Requiring signatures is strongly recommended.
  2. Firmware type, fw_type. Version checking can be enabled/disabled with the NRF_DFU_APP_DOWNGRADE_PREVENTION config.
  3. Hardware version, hw_version.
  4. SoftDevice version, sd_req.
  5. Firmware version, fw_version.
  6. Firmware size to see whether the update will fit. Dual-bank and single-bank updates shows the memory layout for the secure DFU bootloader, which indicates which sizes will be accepted.

If one of these verification steps fails, an error code is sent via the transport.

Version numbers

There are three types of version numbers:

Acceptance rules for versions

Unless version validation is skipped, the dfu_handle_prevalidate() function applies the following acceptance rules to determine whether the image is accepted:

Updates without a SoftDevice

When the bootloader itself does not need the SoftDevice, it can also process updates without SoftDevices. These updates are recognized by the special sd_req value 0x00 as described below.

An empty sd_req list is equivalent to an sd_req list containing a single 0x00.


Documentation feedback | Developer Zone | Subscribe | Updated