Image Parser

Description

Image parser plugin.

Generic image parser interface for Silicon Labs bootloader.

Modules

GBL Parser
GBL parser implementation.
 

Data Structures

struct  ImageProperties_t
 Structure containing state of the image file processed.
 

Macros

#define BTL_IMAGE_CONTENT_APPLICATION   0x01U
 Upgrade image contains application upgrade.
 
#define BTL_IMAGE_CONTENT_BOOTLOADER   0x02U
 Upgrade image contains bootloader upgrade.
 
#define BTL_IMAGE_CONTENT_SE   0x04U
 Upgrade image contains SE upgrade.
 
#define BTL_IMAGE_INSTRUCTION_APPLICATION   0x01U
 Application upgrade should be applied from upgrade image.
 
#define BTL_IMAGE_INSTRUCTION_BOOTLOADER   0x02U
 Bootloader upgrade should be applied from upgrade image.
 
#define BTL_IMAGE_INSTRUCTION_SE   0x04U
 SE upgrade should be applied from upgrade image.
 

Functions

int32_t parser_init (void *context, void *decryptContext, void *authContext, uint8_t flags)
 
int32_t parser_parse (void *context, ImageProperties_t *imageProperties, uint8_t buffer[], size_t length, const BootloaderParserCallbacks_t *callbacks)
 
bool parser_requireAuthenticity (void)
 
bool parser_requireConfidentiality (void)
 
bool parser_requireCertificateAuthenticity (void)
 
bool parser_requireCertificateSignedImage (void)
 
bool parser_requireAntiRollbackProtection (void)
 
uint32_t parser_applicationMinimumVersionValid (void)
 
bool parser_applicationUpgradeVersionValid (ApplicationData_t *app, bool checkRemainingAppUpgrades)
 
uint32_t parser_getApplicationAddress (void)
 
uint32_t parser_getFirstStageBootloaderTable (void)
 
uint32_t parser_getMainBootloaderTable (void)
 
uint32_t parser_getBootloaderUpgradeAddress (void)
 
bool parser_applicationUpgradeValidCallback (ApplicationData_t *app)
 
int32_t parser_verifyCertificate (void *context, void *input, void *blProperties, void *shaState)
 

Function Documentation

int32_t parser_init ( void *  context,
void *  decryptContext,
void *  authContext,
uint8_t  flags 
)

Initialize the parser's context.

Parameters
contextPointer to context for the parser implementation
decryptContextPointer to context for decryption of parsed file
authContextPointer to context for authentication of parsed file
flagsFlags for parser support
Returns
BOOTLOADER_OK if OK, error code otherwise.
int32_t parser_parse ( void *  context,
ImageProperties_t imageProperties,
uint8_t  buffer[],
size_t  length,
const BootloaderParserCallbacks_t callbacks 
)

Parse an image file to extract the binary and some metadata.

Pushes data into the image file parser to be parsed.

Parameters
contextPointer to the specific parser's context variable
imagePropertiesPointer to the image file state variable
bufferPointer to byte array containing data to parse
lengthSize in bytes of the data in buffer
callbacksStruct containing function pointers to be called by the parser to pass the extracted binary data back to BTL.
Returns
BOOTLOADER_OK if OK, error code otherwise.
bool parser_requireAuthenticity ( void  )

Check whether the parser requires images to be signed.

Returns
True if authenticity is required, else false
bool parser_requireConfidentiality ( void  )

Check whether the parser requires images to be encrypted.

Returns
True if confidentiality is required, else false
bool parser_requireCertificateAuthenticity ( void  )

Check whether the parser requires images to be authenticated by the bootloader certificate.

Returns
True if certificate based authenticity is required, else false
bool parser_requireCertificateSignedImage ( void  )

Check whether the parser requires images to be signed by a certificate.

Returns
True if certificate signed image is required, else false
bool parser_requireAntiRollbackProtection ( void  )

Check whether the parser requires rollback protection of applications.

Returns
True if rollback protection of application is required, else false
uint32_t parser_applicationMinimumVersionValid ( void  )

Check the minimum version of the applications that can be accepted.

Returns
Minimum version of the applications that can be accepted.
bool parser_applicationUpgradeVersionValid ( ApplicationData_t app,
bool  checkRemainingAppUpgrades 
)

Check whether the application version is valid and the application can be accepted.

Note
This function will always return true if BOOTLOADER_ROLLBACK_PROTECTION is not enabled from the core plugin option.
Parameters
[in]appPointer to the application data structure contained in the upgrade image.
[in]checkRemainingAppUpgradesCheck 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.
uint32_t parser_getApplicationAddress ( void  )

Return the start address of the application.

Returns
start address of the application.
uint32_t parser_getFirstStageBootloaderTable ( void  )

Return the address of the first stage bootloader table.

Returns
address of the first stage bootloader table.
uint32_t parser_getMainBootloaderTable ( void  )

Return the address of the main bootloader table.

Returns
address of the main bootloader table.
uint32_t parser_getBootloaderUpgradeAddress ( void  )

Return the start address of the bootloader upgrade location.

Returns
start address of the bootloader upgrade location if upgrading is supported, otherwise 0.
bool parser_applicationUpgradeValidCallback ( ApplicationData_t app)

Callback to tell the parser whether to accept the application upgrade present in the upgrade image.

Parameters
[in]appPointer to the application data structure contained in the upgrade image.
Returns
True if the application is accepted, and the parser should continue. False if the application is rejected. If rejected, the parser will abort parsing the image file and return BOOTLOADER_ERROR_PARSER_REJECTED.
int32_t parser_verifyCertificate ( void *  context,
void *  input,
void *  blProperties,
void *  shaState 
)

Verify GBL certificate.

Note
The behavior of this function depends on the context state.
Parameters
[in,out]contextGBL parser context
[in]inputInput data
[in]blPropertiesPointer to ApplicationProperties_t of bootloader
[in,out]shaStatePointer to Sha256Context_t used to store SHA256 of GBL certificate
Returns
BOOTLOADER_ERROR_PARSER_PARSED if done parsing the current input buffer. BOOTLOADER_OK if input data is stored in the internal buffer. BOOTLOADER_OK if the certificate in GBL is accepted. BOOTLOADER_ERROR_PARSER_SIGNATURE if the certificate in GBL is rejected.