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
include/bl_validation.h
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:
-
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.
-
typedef bool (*bl_validate_firmware_t)(uint32_t fw_dst_address, uint32_t fw_src_address)