Description

Methods to verify and bootload application images.

Functions
uint32_t	bootload_getUpgradeLocation (void)

uint32_t	bootload_getBootloaderVersion (void)

bool	bootload_getApplicationVersion (uint32_t *version)

bool	bootload_getSeVersion (uint32_t *version)

bool	bootload_checkApplicationPropertiesMagic (void *appProperties)

bool	bootload_checkApplicationPropertiesVersion (void *appProperties)

bool	bootload_verifyApplication (uint32_t startAddress)

void	bootload_bootloaderCallback (uint32_t offset, uint8_t data[], size_t length, void *context)

void	bootload_applicationCallback (uint32_t address, uint8_t data[], size_t length, void *context)

bool	bootload_commitBootloaderUpgrade (uint32_t upgradeAddress, uint32_t size)

bool	bootload_verifyApplicationVersion (uint32_t appVersion, bool checkRemainingAppUpgrades)

bool	bootload_storeApplicationVersion (uint32_t startAddress)

uint32_t	bootload_remainingApplicationUpgrades (void)

void	bootload_storeApplicationVersionResetMagic (void)

void	bootload_removeStoredApplicationVersions (void)

uint32_t	bootload_getApplicationVersionStorageCapacity (void)

uint32_t *	bootload_getApplicationVersionStoragePtr (uint32_t index)

bool	bootload_gotCertificate (void *appProp)

bool	bootload_verifyCertificate (void *cert)

bool	bootload_verifyApplicationCertificate (void appProp, void gotCert)

bool	bootload_checkSeUpgradeVersion (uint32_t upgradeVersion)

bool	bootload_commitSeUpgrade (uint32_t upgradeAddress)

Function Documentation

uint32_t bootload_getUpgradeLocation ( void )

Get base address of the bootloader upgrade image.

Returns: Returns the base address of bootloader upgrade image.

uint32_t bootload_getBootloaderVersion ( void )

Get the version of the bootloader.

Returns: Returns the version of the bootloader.

bool bootload_getApplicationVersion ( uint32_t * version )

Get the version of the application.

Parameters

[out] version The retrieved application version

Returns: Returns true if the version was retrieved successfully

bool bootload_getSeVersion ( uint32_t * version )

Get the version of the SE.

Parameters

[out] version The retrieved SE version

Returns: Returns true if the version was retrieved successfully.

bool bootload_checkApplicationPropertiesMagic ( void * appProperties )

Check application properties magic.

Parameters

appProperties Pointer to ApplicationProperties_t

Returns: True if the application properties magic is valid.

bool bootload_checkApplicationPropertiesVersion ( void * appProperties )

Check application properties struct version.

Parameters

appProperties Pointer to ApplicationProperties_t

Returns: True if the application properties struct version is compatible with the bootloader.

bool bootload_verifyApplication ( uint32_t startAddress )

Verify the application image stored in the Flash memory starting at the address startAddress.

If secure boot is enforced, the function will only return true if the cryptographic signature of the application is valid. Else, the application is verified according to the signature type defined in the ApplicationProperties_t structure embedded in the application. Silicon Labs wireless stacks declare this structure. Applications, which are not using a full wireless stack may need to instantiate the structure.

Examples of results when secure boot is not enforced:

App has no signature: Valid if initial stack pointer and program counter have reasonable values
App has CRC checksum: Valid if checksum is valid
App has ECDSA signature: Valid if ECDSA signature is valid.

When secure boot is enforced, only ECDSA-signed applications with a valid signature are considered valid.

Parameters

[in] startAddress Starting address of the application

Returns: True if the image is deemed valid

void bootload_bootloaderCallback	(	uint32_t	`offset,`
		uint8_t	`data[],`
		size_t	`length,`
		void *	`context`
	)

Bootloader upgrade callback implementation.

Parameters

`offset`	Offset of bootloader data (byte counter incrementing from 0)
`data`	Raw bootloader data
`length`	Size in bytes of raw bootloader data.
`context`	A context variable defined by the implementation that is implementing this callback.

void bootload_applicationCallback	(	uint32_t	`address,`
		uint8_t	`data[],`
		size_t	`length,`
		void *	`context`
	)

Image data callback implementation.

Parameters

`address`	Address (inside the raw image) the data starts at
`data`	Raw image data
`length`	Size in bytes of raw image data. Always constrained to a multiple of four.
`context`	A context variable defined by the implementation that is implementing this callback.

bool bootload_commitBootloaderUpgrade	(	uint32_t	`upgradeAddress,`
		uint32_t	`size`
	)

Perform a bootloader upgrade using the upgrade image present at upgradeAddress with length size.

If the bootloader upgrade process starts successfully, this function does not return and execution will resume from the reset handler of the upgraded bootloader.

Parameters

[in]	`upgradeAddress`	The starting address of the upgrade image
[in]	`size`	The length of the upgrade image in bytes

Returns: False if the bootloader upgrade process didn't start

bool bootload_verifyApplicationVersion	(	uint32_t	`appVersion,`
		bool	`checkRemainingAppUpgrades`
	)

Verify the application version for rollback protection.

Parameters

[in]	`appVersion`	Application version to be checked.
[in]	`checkRemainingAppUpgrades`	Check remaining application upgrades.

Returns: True if the application version is higher or equal than the application versions seen. False if the application version is lower than the application versions seen. False if no remaining application upgrades are left when checkRemainingAppUpgrades is true.

bool bootload_storeApplicationVersion ( uint32_t startAddress )

Store the application version.

Note: Only the version of the verified application should be stored.

Parameters

startAddress Start address of application.

Returns: True if application version is successfully stored.

uint32_t bootload_remainingApplicationUpgrades ( void )

Count the total remaining number of application upgrades.

Returns: remaining number of application upgrades.

void bootload_storeApplicationVersionResetMagic ( void )

Store application version reset magic.

Note: Store application version reset magic to ensure that application versions are cleaned after a bootloader upgrade.

void bootload_removeStoredApplicationVersions ( void )

Clean the application versions seen.

Note: The application versions are cleaned only if this is requested with a magic and the application version storage is not already empty.

uint32_t bootload_getApplicationVersionStorageCapacity ( void )

Get the application version storage capacity.

Returns: Application version storage capacity.

uint32_t* bootload_getApplicationVersionStoragePtr ( uint32_t index )

Get the address of the application version storage buffer.

Parameters

index Index of the application version storage buffer.

Returns: Address of the application version storage buffer with the given index.

bool bootload_gotCertificate ( void * appProp )

Check whether the application contains a certificate.

Parameters

appProp Pointer to ApplicationProperties_t of application.

Returns: True if application contains a certificate.

bool bootload_verifyCertificate ( void * cert )

Verify a certificate with a bootloader certificate.

Parameters

cert Pointer to ApplicationCertificate_t .

Returns: True if certificate is verified.

bool bootload_verifyApplicationCertificate	(	void *	`appProp,`
		void *	`gotCert`
	)

Verify the application certificate.

Note: This function will always return true if certificate support is not enabled. Also true if appProp does not contain any certificate and direct signed applications can be accepted.

Parameters

`appProp`	Pointer to ApplicationProperties_t of application.
`gotCert`	Boolean to store application certificate presence.

Returns: True if application certificate is verified.

bool bootload_checkSeUpgradeVersion ( uint32_t upgradeVersion )

Check that an SE upgrade with a given version number is allowed to be installed.

This will only be true if the upgrade version is higher than the running version.

Parameters

[in] upgradeVersion The version of the SE upgrade image

Returns: True if the SE upgrade image should be installed

bool bootload_commitSeUpgrade ( uint32_t upgradeAddress )

Perform an SE upgrade using the upgrade image present at upgradeAddress.

If the SE upgrade process starts successfully, this function does not return and execution will resume from the reset handler after the SE upgrade is complete.

Parameters

[in] upgradeAddress The starting address of the upgrade image.

Returns: False if the SE upgrade process didn't start.

BootloadBootloader Core

Description

Functions

Function Documentation