Bootloader firmware validation

The bootloader firmware validation library provides the function that the nRF Secure Immutable Bootloader uses to validate a firmware image before booting it.

The API is public because applications that are booted by the immutable bootloader can call the function from this library using the bootloader’s code, through external APIs. See External APIs for more information. Using this mechanism can be useful when the application receives a DFU package and wants to determine whether it will be accepted by the bootloader.

Validation

The bl_validate_firmware() function validates the following information:

API documentation

Header file: include/bl_validation.h
Source files: subsys/bootloader/bl_validation/
group bl_validation

Typedefs

typedef bool (*bl_validate_firmware_t)(uint32_t fw_dst_address, uint32_t fw_src_address)

Functions

bool bl_validate_firmware(uint32_t fw_dst_address, uint32_t fw_src_address)

Function for validating firmware.

This will run a series of checks on the fw_src_address contents, then locate the validation info and check the signature of the image.

Parameters:
  • fw_dst_address[in] Address where the firmware will be written.

  • fw_src_address[in] Address of the firmware to be validated.

Return values:
  • true – if the image is valid

  • false – if the image is invalid

bool bl_validate_firmware_available(void)

Whether bl_validate_firmware() is available.

This is only relevant when CONFIG_BL_VALIDATE_FW_EXT_API_OPTIONAL is set.

Return values:
bool bl_validate_firmware_local(uint32_t fw_address, const struct fw_info *fwinfo)

Function for validating firmware in place.

See bl_validate_firmware for more details.

Note

This function is only available to the bootloader.

int set_monotonic_version(uint16_t version, uint16_t slot)

Write 15 bit version and 1 bit slot to a 16 bit monotonic counter.

Parameters:
  • version[in] Firmware version. Can be any unsigned 15 bit value.

  • slot[in] Slot where firmware is located. Must be 0 or 1.

Returns:

See set_monotonic_counter.

int get_monotonic_version(uint16_t *version_out)

Write the stored 15-bit version to the 16-bit output parameter ‘version_out’.

Parameters:
  • version_out[out] Firmware version. Can be any unsigned 15-bit value.

Return values:
  • 0 – Success

  • -EINVAL – Error during reading the version or version is NULL.

int get_monotonic_slot(uint16_t *slot_out)

Write the stored slot to the output parameter ‘slot_out’.

Parameters:
  • slot_out[out] Slot where firmware is located. Can be 0 or 1.

Return values:
  • 0 – Success

  • -EINVAL – Error during reading the version or version is NULL.

struct bl_validate_fw_ext_api
#include <bl_validation.h>

Structure describing the BL_VALIDATE_FW EXT_API.