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:

• The digest and the signature of the whole image (see bl_root_of_trust_verify())

• The fields of the fw_info struct that is part of the firmware image (see Firmware 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

• true – bl_validate_firmware() can be called and should work correctly.

• false – bl_validate_firmware() is unavailable and will always return false because the underlying EXT_API is unavailable.

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.

uint16_t get_monotonic_version(uint16_t *slot_out)

Read 15 bit version and 1 bit slot from a 16 bit monotonic counter.

Parameters

• slot_out – [out] Slot where firmware is located. Can be NULL.

Returns

Firmware version. Can be any unsigned 15 bit value.

struct bl_validate_fw_ext_api

#include <bl_validation.h>

Structure describing the BL_VALIDATE_FW EXT_API.