Bootloader firmware validation

The bootloader firmware validation library provides the function that the 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 via 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

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

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

Return Value

• 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 Value

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

• false: bl_validate_firmware() is unavailable and will always return false because the undelying 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 version and slot to monotonic counter.

The version is left-shifted 1 bit, and the slot is place as the LSB.

Return

See set_monotonic_counter.

Parameters

• [in] version: Firmware version.

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

uint16_t get_monotonic_version(uint16_t *slot_out)

Read version and slot from monotonic counter.

Return

Firmware version

Parameters

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

struct bl_validate_fw_ext_api

#include <bl_validation.h>

Structure describing the BL_VALIDATE_FW EXT_API.