Secure Bootloader Sample Reference Function Documentation

 

BL_AttestInitialize

BL_AttestStatus_t BL_AttestInitialize()

 

Initialize the attestation feature.

 

@returnBL_ATTEST_NO_ERROR or BL_ATTEST_INIT_FAILED.

 

Location: bl_attestation.h:106

 

BL_AttestAcceptKey

BL_AttestStatus_t BL_AttestAcceptKey(BL_AttestKeyType_t keyType, size_t privKeySize, size_t pubKeySize)

 

Determine if it is okay to accept a key injection request.

 

Location: bl_attestation.h:115

 

Parameters

Direction Name Description

keyType

The type of key being injected.

privKeySize

The size in bytes of the private key buffer.

pubKeySize

The maximum size of the buffer to hold the public key.

 


Return


BL_ATTEST_NO_ERROR if the request accepted, error state otherwise.

 

BL_AttestFindPublicKeyHash

BL_AttestStatus_t BL_AttestFindPublicKeyHash(uint8_t * hash)

 

Retrieve the SHA256 hash of the public key if it exists.

 

Location: bl_attestation.h:123

 

Parameters

Direction Name Description

hash

A buffer to hold the hash, no checking is performed on the size.

 


Return


BL_ATTEST_NO_ERROR if success, otherwise an error status.

 

BL_AttestInjectKey

BL_AttestStatus_t BL_AttestInjectKey(uint8_t * key, size_t keySize, BL_AttestKeyType_t type, uint8_t * publicKey, size_t publicKeyMaxSize, size_t * publicKeySize)

 

Inject or create an attestation key.

 

If a key is provided then the private component key is stored and the public component is returned. If no key is provided then a new key is generated and the private component is stored and the public returned. If a symmetric (AES) key is requested then the key is stored and returned.

 

Location: bl_attestation.h:140

 

Parameters

Direction Name Description

key

The key to be stored or NULL if the key should be generated.

keySize

The number of bytes in the provided key, or zero.

type

the type of the key being provided or requested.

publicKey

The buffer into which the public key should be written.

publicKeyMaxSize

the maximum size of the provided buffer in bytes.

publicKeySize

The actual size of the returned key in bytes.

 


Return


NO_ERROR if the key is successfully returned otherwise an error.

 

BL_AttestGetToken

BL_AttestStatus_t BL_AttestGetToken(uint8_t * challenge, BL_AttestationChallengeSize_t challengeSize, uint8_t * token, size_t * tokenSize)

 

return the Entity Attestation Token associated with the device.

 

Location: bl_attestation.h:153

 

Parameters

Direction Name Description

challenge

The challenge request from the caller.

challengeSize

The requested challenge size.

token

The buffer into which the token should be written.

tokenSize

This provides the maximum size of the token buffer as well as returns the actual size of the returned token.

 


Return


Status of the get token operation.

 

BL_AttestGetTokenSize

BL_AttestStatus_t BL_AttestGetTokenSize(BL_AttestationChallengeSize_t challengeSize, size_t * tokenSize)

 

return the size of the Entity Attestation Token associated with the device.

 

Location: bl_attestation.h:164

 

Parameters

Direction Name Description

challengeSize

The requested challenge size.

tokenSize

This returns the actual size of any returned token.

 


Return


Status of the get token size operation.

 

BL_CheckRemapAddressSpace

uint32_t BL_CheckRemapAddressSpace(uint32_t base, uint32_t address)

 

Determine download address based on given address which may be in bootloader or application space.

 

Location: bl_check.h:87

 

Parameters

Direction Name Description

base

The base address of the application being checked.

address

The given address in either bootloader or application space.

 


Return


The adjusted address.

 

BL_CheckGetApplicationSize

uint32_t BL_CheckGetApplicationSize(uint32_t address)

 

Fetch the application size from a buffer defined by base address of the application vector table.

 

Location: bl_check.h:95

 

Parameters

Direction Name Description

address

The address of the base of the vector table.

 


Return


the size derived from the application or zero if invalid.

 

BL_CheckRelocatedApplicationSize

uint32_t BL_CheckRelocatedApplicationSize(uint32_t address)

 

Fetch the application size from a buffer defined by base address of the application vector table.

 

Location: bl_check.h:103

 

Parameters

Direction Name Description

address

The address of the base of the vector table.

 


Return


the size derived from the application or zero if invalid.

 

BL_CheckIfImageUpdateAvailable

BL_UpdateType_t BL_CheckIfImageUpdateAvailable()

 

Check for a valid update using the non-secure file format.

 

When dealing with a non-secure image, the following checks must be made:

 

Location: bl_check.h:116

 

  • The address must be properly aligned and within a sensible range.
  • The stack pointer resides in RAM, is 64 bit aligned, allows 10 words.
  • The reset ISR follows the vector table address The address to check for a valid image. extent The maximum extent of the area holding the image.

    Return


    Type of image update available in download area.

 

BL_CheckIfSecureImageUpdateAvailable

bool BL_CheckIfSecureImageUpdateAvailable()

 

Check for a valid update using the secure file format.

 

When dealing with a secure image, the following checks must be made:

 

Location: bl_check.h:132

 

  • The address must be properly aligned and within a sensible range.
  • The stack pointer resides in RAM, is 64 bit aligned, allows 10 words.
  • The reset ISR follows the vector table.
  • The full certificate chain must be authenticated. updateType The type of update being requested. address The address to check for a valid image. extent The maximum extent of the area holding the image.

    Return


    True if the image has security signature, false otherwise.

 

BL_CheckFindSecondaryImageLocation

void BL_CheckFindSecondaryImageLocation(uint32_t primaryBase, uint32_t primaryExtent, uint32_t * secondaryBase, uint32_t * secondaryExtent)

 

Based on a primary image address, calculate the potential location and extent of any secondary image.

 

Location: bl_check.h:144

 

Parameters

Direction Name Description

primaryBase

The base address of the primary image, used to locate the secondary one.

primaryExtent

The maximum extent of the primary application;

secondaryBase

secondaryExtent

 

BL_ConfigIsValid

BL_ConfigStatus_t BL_ConfigIsValid(BL_AppConfiguration_t * configBase)

 

Helper function to return the configuration area status.

 

Location: bl_configuration.h:85

 

Parameters

Direction Name Description

configBase

Defines the base address of the configuration block.

 


Return


BL_CONFIG_OKAY if the configuration area has a valid CRC, BL_CONFIG_CORRUPT otherwise.

 

BL_ConfigCertificateAddress

uint32_t BL_ConfigCertificateAddress(BL_AppConfiguration_t * configBase, BL_LoaderCertType_t cert)

 

Fetch the address of the requested structure.

 

Location: bl_configuration.h:93

 

Parameters

Direction Name Description

configBase

Defines the base address of the configuration block.

cert

A requested certificate.

 


Return


The address of the requested certificate or zero if invalid request.

 

BL_CryptoInitialize

BL_CryptoStatus_t BL_CryptoInitialize()

 

Initialize the basic crypto system.

 

Location: bl_crypto.h:92

 


Return


BL_CRYPTO_NO_ERROR if success otherwise an error state.

 

BL_CryptoGetBootSeed

uint8_t * BL_CryptoGetBootSeed()

 

Fetch the boot seed.

 

This is calculated on first boot.

 

Location: bl_crypto.h:103

 


Return


A pointer to a buffer containing the boot seed random number.

 

BL_CryptoHash

BL_CryptoStatus_t BL_CryptoHash(uint8_t * buffer, uint32_t base, uint32_t length)

 

Hash a block of memory using SHA256.

 

Location: bl_crypto.h:112

 

Parameters

Direction Name Description

buffer

A pointer to a buffer to which the should be written.

base

The base address of the memory to be hashed.

length

The length in bytes of the memory to be hashed.

 


Return


BL_CRYPTO_NO_ERROR if success otherwise an error state.

 

BL_CryptoRSAKeySize

uint16_t BL_CryptoRSAKeySize(BL_CryptoRSAKeyType_t type, bool public)

 

Calculate the size required to serialize a given RSA private key.

 

Location: bl_crypto_rsa.h:78

 

Parameters

Direction Name Description

type

The type of the key to calculate the size for.

public

Flag indicating the key being considered is public or private.

 


Return


The calculated size or zero if the type is invalid.

 

BL_CryptoRSASerialiseKey

BL_CryptoStatus_t BL_CryptoRSASerialiseKey(BL_CryptoRSAKeyType_t type, mbedtls_rsa_context * pKey, uint8_t * buffer, size_t length, bool public)

 

Serialize an RSA key to a byte buffer.

 

Location: bl_crypto_rsa.h:90

 

Parameters

Direction Name Description

type

The type of the key to be serialized.

pKey

a pointer to a RSA context containing a key.

buffer

The buffer into which the key should be written.

length

The length of the buffer receiving the serialized key.

public

True if the public components of the key should be saved.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

BL_CryptoRSADeserialiseKey

BL_CryptoStatus_t BL_CryptoRSADeserialiseKey(BL_CryptoRSAKeyType_t type, mbedtls_rsa_context * pKey, uint8_t * buffer, size_t length, bool public)

 

Deserialize an RSA key from a byte buffer.

 

Location: bl_crypto_rsa.h:103

 

Parameters

Direction Name Description

type

The type of the key to be deserialized.

pKey

a pointer to a RSA context containing a key.

buffer

The buffer from which the key should be read.

length

The length of the buffer holding the serialized key.

public

True if the public components of the key should be extracted.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

BL_CryptoRSAGenerateKey

BL_CryptoStatus_t BL_CryptoRSAGenerateKey(BL_CryptoRSAKeyType_t keyType, mbedtls_rsa_context * pKey)

 

Generate a new RSA key of the given type.

 

Location: bl_crypto_rsa.h:113

 

Parameters

Direction Name Description

keyType

The type of the key to be generated.

pKey

A pointer to an uninitialised rsa context to hold the key.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

BL_CryptoRSASignHash

BL_CryptoStatus_t BL_CryptoRSASignHash(BL_CryptoRSAKeyType_t keyType, mbedtls_rsa_context * pKey, uint8_t * sign, size_t signLength, uint8_t * hash, size_t hashLength)

 

Sign a message hash using a private RSA key.

 

Location: bl_crypto_rsa.h:127

 

Parameters

Direction Name Description

keyType

The type of the RSA key to be used when signing the message.

pKey

A pointer to a private key.

sign

The resultant signature for the message.

signLength

The length of the buffer to which the signature is written.

hash

The resultant hash of the message.

hashLength

The length of the buffer holding the hash.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

BL_CryptoRSASignMessage

BL_CryptoStatus_t BL_CryptoRSASignMessage(BL_CryptoRSAKeyType_t keyType, mbedtls_rsa_context * pKey, uint8_t * msg, size_t msgLength, uint8_t * sign, size_t signLength, uint8_t * hash, size_t hashLength)

 

Sign a message using a private RSA key.

 

Location: bl_crypto_rsa.h:149

 

Parameters

Direction Name Description

keyType

The type of the RSA key to be used when signing the message.

pKey

A pointer to a private key.

msg

A pointer to a buffer holding the message to be signed.

msgLength

The length of the message to be signed.

sign

The resultant signature for the message.

signLength

The length of the buffer to which the signature is written.

hash

The resultant hash of the message.

hashLength

The length of the buffer holding the hash.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

NOTE: This method is suitable for signing small messages which are held in RAM, if larger messages need to be handled it may be more suitable to perform the hashing separately using BL_CryptoHash and then sign the hash in isolation using BL_CryptoRSASignHashRSA.

 

BL_CryptoRSAVerifyMessage

BL_CryptoStatus_t BL_CryptoRSAVerifyMessage(mbedtls_rsa_context * pKey, uint8_t * sign, uint8_t * hash, size_t hashLength)

 

Verify that a given hash and signature are consistent.

 

Location: bl_crypto_rsa.h:162

 

Parameters

Direction Name Description

pKey

A pointer to a private key.

sign

The signature to be verified.

hash

The hash of the original message which has been signed.

hashLength

The length of the hash.

 


Return


BL_CRYPTO_NO_ERROR if success, an error state otherwise.

 

BL_EATPopulate

BL_EATStatus_t BL_EATPopulate(uint8_t * challenge, size_t size)

 

Populates a buffer with the contents of the entity attestation token.

 

Location: bl_eat.h:98

 

Parameters

Direction Name Description

challenge

A pointer to the challenge buffer.

size

The size of the challenge in bytes.

 


Return


BL_EAT_NO_ERROR if token written otherwise an error state.

 

BL_EATSize

size_t BL_EATSize(size_t challengeSize)

 

Calculate the expected size of the EAT token once converted to CBOR.

 

Location: bl_eat.h:105

 

Parameters

Direction Name Description

challengeSize

The size in bytes fo the challenge accompanying the EAT.

 


Return


the number of bytes required to hold the EAT.

 

BL_FCSInitialize

BL_FCSStatus_t BL_FCSInitialize(uint8_t * buffer, size_t length, BL_FCS_t fcs)

 

Initialize the FCS module, deriving the selected algorithm from the provided sample data.

 

Location: bl_fcs.h:86

 

Parameters

Direction Name Description

buffer

A buffer of bytes to be FCS'd.

length

The number of bytes.

fcs

The expected FCS value.

 


Return


BL_FCS_NO_ERROR if the FCS algorithm can be identified. BL_FCS_UNRECOGNIZED if the FCS algorithm cannot be identified.

 

BL_FCSQuery

BL_FCSAlgorithm_t BL_FCSQuery()

 

Query the currently selected FCS algorithm.

 

Location: bl_fcs.h:92

 


Return


The currently selected algorithm.

 

BL_FCSAuthenticationRequired

bool BL_FCSAuthenticationRequired()

 

Provides a mechanism to determine if the loading process should apply authentication to the protocol and images.

 

Location: bl_fcs.h:99

 


Return


True if authentication is required

 

BL_FCSSelect

BL_FCSStatus_t BL_FCSSelect(BL_FCSAlgorithm_t algo)

 

Select a specific FCS algorithm.

 

Location: bl_fcs.h:108

 

Parameters

Direction Name Description

algo

Selected from BL_FCSAlgorithm_t.

 


Return


BL_FCS_NO_ERROR If the algorithm is valid. BL_FCS_UNRECOGNIZED If the algorithm is not valid.

 

BL_FCSCheck

BL_FCSStatus_t BL_FCSCheck(uint8_t * buffer, size_t length, BL_FCS_t fcs)

 

Check the validity of a buffer against a given FCS.

 

Location: bl_fcs.h:119

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a FCS over.

length

The number of bytes.

fcs

The expected FCS value.

 


Return


BL_FCS_VALID if the FCS matches the data. BL_FCS_INVALID if the FCS does not match the data.

 

BL_FCSCalculate

BL_FCSStatus_t BL_FCSCalculate(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Calculate the FCS of a given buffer.

 

Location: bl_fcs.h:130

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a FCS over.

length

The number of bytes.

fcs

The calculated FCS value.

 


Return


BL_FCS_NO_ERROR if the FCS can be calculated. BL_FCS_INVALID if an error is detected when calculating the FCS.

 

BL_FCSAccumulateCRC

uint32_t BL_FCSAccumulateCRC(uint8_t * buffer, size_t length)

 

Helper method to accumulate a CRC given a buffer and a length.

 

Location: bl_fcs.h:141

 

Parameters

Direction Name Description

buffer

A buffer of bytes to calculate a CRC on.

length

The number of bytes.

 

NOTE: This is expected to be used for RAM buffers where the use of the flash copier can't be used. The CRC engine should be initialised prior to calling this function.

 

BL_EncryptInitialize

BL_EncryptionStatus_t BL_EncryptInitialize(const uint8_t * label, size_t length)

 

Initialization function for the encryption layer.

 

Location: bl_file_encryption.h:85

 

Parameters

Direction Name Description

label

A label value to be used when creating the derived key.

length

The length of the label in bytes.

 


Return


BL_ENCRYPT_NO_ERROR if the initialization succeeds.

 

BL_EncryptResetEncryption

BL_EncryptionStatus_t BL_EncryptResetEncryption(const uint8_t * iv)

 

Reset the encryption operation and introduce a new initial value.

 

Location: bl_file_encryption.h:96

 

Parameters

Direction Name Description

iv

The new initial value, must be a pointer to a buffer of BL_ENCRYPT_KEY_SIZE_BYTES bytes.

 

BL_EncryptResetDecryption

BL_EncryptionStatus_t BL_EncryptResetDecryption(const uint8_t * iv)

 

Reset the decryption operation and introduce a new initial value.

 

Location: bl_file_encryption.h:106

 

Parameters

Direction Name Description

iv

The new initial value, must be a pointer to a buffer of BL_ENCRYPT_KEY_SIZE_BYTES bytes.

 

BL_EncryptEncryptBuffer

BL_EncryptionStatus_t BL_EncryptEncryptBuffer(uint8_t * buffer, size_t length)

 

Encrypt a buffer using the internally derived key.

 

Location: bl_file_encryption.h:117

 

Parameters

Direction Name Description

buffer

A pointer to a buffer to be encrypted.

length

The length of the buffer being encrypted.

 


Return


BL_ENCRYPT_NO_ERROR if encryption succeeds, otherwise error.

 

NOTE: The length must be a a multiple of 16 bytes otherwise an error will be reported.

 

BL_EncryptDecryptBuffer

BL_EncryptionStatus_t BL_EncryptDecryptBuffer(uint8_t * buffer, size_t length)

 

Decrypt a buffer using the internally derived key.

 

Location: bl_file_encryption.h:128

 

Parameters

Direction Name Description

buffer

A pointer to a buffer to be decrypted.

length

The length of the buffer being decrypted.

 


Return


BL_ENCRYPT_NO_ERROR if decryption succeeds, otherwise error.

 

NOTE: The length must be a a multiple of 16 bytes otherwise an error will be reported.

 

BL_EncryptComplete

BL_EncryptionStatus_t BL_EncryptComplete()

 

Complete the current encryption or decryption operation.

 

Location: bl_file_encryption.h:134

 


Return


BL_ENCRYPT_NO_ERROR if success, otherwise error.

 

BL_FlashInitialize

void BL_FlashInitialize()

 

Initialize the flash subsystem.

 

Location: bl_flash.h:55

 

BL_FlashSaveSector

FlashStatus_t BL_FlashSaveSector(uint8_t * address, size_t length, uint8_t * buffer)

 

Save a buffer to a specified flash address.

 

Location: bl_flash.h:67

 

Parameters

Direction Name Description

address

The address in flash to save the buffer.

length

The number of bytes to save.

buffer

A pointer to a buffer of data to be written.

 


Return


FLASH_ERR_NONE if the operation is successful otherwise an error code the flash library.

 

NOTE: The start address is expected to start on a sector boundary.

 

BL_ImageInitialize

BL_ImageType_t BL_ImageInitialize(uint8_t * address, size_t length, uint32_t crc)

 

Initialize the image module for a specific set of image attributes.

 

Location: bl_image.h:98

 

Parameters

Direction Name Description

address

The base address of the image being loaded.

length

The length of the image in bytes.

crc

the crc of the image being loaded.

 


Return


The type of image recognized.

 

BL_ImageAddress

uint32_t BL_ImageAddress(uint32_t address)

 

Convert an address to take into account potential offsets.

 

Location: bl_image.h:107

 

Parameters

Direction Name Description

address

The address in an image.

 


Return


The converted address.

 

BL_ImageAddressRange

void BL_ImageAddressRange(uint8_t * address, size_t length, BL_ImageSplitRange_t * range)

 

Helper routine which allows access of the image as a contiguous block of addresses, wrapping around the reserved block.

 

Location: bl_image.h:118

 

Parameters

Direction Name Description

address

An address within an image that may need to be adjusted.

length

the length of the address range.

range

A split range object that indicates where the address range needs to be split.

 

BL_ImageCopyMemoryRange

void BL_ImageCopyMemoryRange(uint8_t * dst, BL_ImageSplitRange_t * range)

 

Copy a possibly split memory range to a contiguous buffer.

 

Location: bl_image.h:127

 

Parameters

Direction Name Description

dst

The destination buffer.

range

The range defining the source locations.

 

BL_ImageSaveBlock

BL_ImageStatus_t BL_ImageSaveBlock(BL_ImageOperation_t * operation)

 

Save a block of data from a RAM buffer to the next block in Flash.

 

Location: bl_image.h:135

 

Parameters

Direction Name Description

operation

Defines the address and length of the block to be saved.

 


Return


Status code indicating if the save operation failed

 

BL_ImageVerify

BL_ImageStatus_t BL_ImageVerify()

 

Verify the most recently loaded image.

 

Location: bl_image.h:144

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_VERIFY_ERROR If the CRC does not match the data.

 

BL_ImageAuthenticate

BL_ImageStatus_t BL_ImageAuthenticate(BL_ImageType_t imageType, uint32_t * address, size_t length, bool verifyImages)

 

Authenticate a loaded image.

 

Location: bl_image.h:157

 

Parameters

Direction Name Description

imageType

The type of the image being authenticated.

address

The base address of the image to be authenticated.

length

The size of the area in bytes.

verifyImages

Flag indicating that the s/w images must be validated.

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_AUTHENTICATE_ERROR If the authentication fails.

 

BL_ImageAuthenticateCurrent

BL_ImageStatus_t BL_ImageAuthenticateCurrent()

 

Authenticate the most recently loaded image.

 

Location: bl_image.h:167

 


Return


BL_IMAGE_NO_ERROR If the CRC matches the data. BL_IMAGE_AUTHENTICATE_ERROR If the authentication fails.

 

BL_ImageIsValid

bool BL_ImageIsValid(uint32_t address, size_t length)

 

Check if there is a valid image to start.

 

Location: bl_image.h:176

 

Parameters

Direction Name Description

address

The address of the image in flash.

length

The length of the image in bytes.

 


Return


True if there is a valid application to start. False otherwise.

 

BL_ImageSaveAddress

uint32_t BL_ImageSaveAddress(BL_ImageType_t imageType, uint32_t address)

 

Return the download address corresponding to the requested address.

 

Location: bl_image.h:185

 

Parameters

Direction Name Description

imageType

The type of the image being authenticated.

address

The requested address

 


Return


The download address

 

BL_ImageStartApplication

void BL_ImageStartApplication(uint32_t imageBaseAddress)

 

Start the image stored in flash.

 

Location: bl_image.h:192

 

Parameters

Direction Name Description

imageBaseAddress

The base address of the image to be started

 

BL_LoaderPerformFirmwareLoad

void BL_LoaderPerformFirmwareLoad()

 

Perform a firmware update over the UART interface.

 

Location: bl_loader.h:147

 

BL_LoaderCertificateAddress

uint32_t BL_LoaderCertificateAddress(BL_LoaderCertType_t cert)

 

Fetch the address of the requested structure.

 

Location: bl_loader.h:154

 

Parameters

Direction Name Description

cert

A requested certificate.

 


Return


The address of the requested certificate or zero if invalid request.

 

BL_CBORInitialize

BL_CBORStatus_t BL_CBORInitialize(uint8_t * buffer, size_t size)

 

Initialize the CBOR renderer giving it a buffer to render to.

 

Location: bl_mini_cbor.h:73

 

Parameters

Direction Name Description

buffer

A pointer to a buffer to render to.

size

The size of the buffer in bytes.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORReset

BL_CBORStatus_t BL_CBORReset()

 

Reset the CBOR renderer pointers to the initial state.

 

Location: bl_mini_cbor.h:80

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORUsed

BL_CBORStatus_t BL_CBORUsed(size_t * size)

 

Provide an indication of the amount of the buffer that has been used.

 

Location: bl_mini_cbor.h:88

 

Parameters

Direction Name Description

size

Pointer to size_t object to receive the number of used bytes.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORCurrent

uint8_t * BL_CBORCurrent()

 

Retrieve the current pointer onto the render buffer.

 

Location: bl_mini_cbor.h:95

 


Return


A pointer to the next write point of the buffer.

 

BL_CBORAddInteger

BL_CBORStatus_t BL_CBORAddInteger(uint32_t value)

 

Add an integer to the CBOR buffer.

 

Location: bl_mini_cbor.h:104

 

Parameters

Direction Name Description

value

The value to render to the buffer..

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORAddBuffer

BL_CBORStatus_t BL_CBORAddBuffer(uint8_t * value, uint32_t size)

 

Add a fixed size buffer to the CBOR buffer.

 

Location: bl_mini_cbor.h:113

 

Parameters

Direction Name Description

value

A pointer to an array of bytes to be added.

size

The size of the buffer to add.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORAddMap

BL_CBORStatus_t BL_CBORAddMap(uint32_t numItems)

 

Add a map with a fixed number of entries to the CBOR buffer.

 

Location: bl_mini_cbor.h:121

 

Parameters

Direction Name Description

numItems

The number of items that will be in the map.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORAddMapPair

BL_CBORStatus_t BL_CBORAddMapPair(uint32_t tag, uint8_t * value, uint32_t size)

 

Add a key value pair to a map.

 

Location: bl_mini_cbor.h:131

 

Parameters

Direction Name Description

tag

The key value to add.

value

a pointer to a buffer of data to write.

size

The number of butes in the value being written.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORSizeInteger

size_t BL_CBORSizeInteger(uint32_t value)

 

Retrieve the rendered size of an integer value.

 

Location: bl_mini_cbor.h:140

 

Parameters

Direction Name Description

value

The value to size.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORSizeBuffer

size_t BL_CBORSizeBuffer(uint32_t size)

 

Retrieve the rendered size of a buffer.

 

Location: bl_mini_cbor.h:148

 

Parameters

Direction Name Description

size

The number of bytes in the buffer being renedered.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORSizeMap

size_t BL_CBORSizeMap(uint32_t numItems)

 

Retrieve the number of bytes in a rendered map header.

 

Location: bl_mini_cbor.h:156

 

Parameters

Direction Name Description

numItems

the number of items in the map.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_CBORSizeMapPair

size_t BL_CBORSizeMapPair(uint32_t tag, uint32_t size)

 

Retrieve the rendered size of a key value pair.

 

Location: bl_mini_cbor.h:165

 

Parameters

Direction Name Description

tag

The key value.

size

The size of the buffer associated with the value.

 


Return


BL_CBOR_NO_ERROR if everything is okay, otherwise error status.

 

BL_RecoveryInitialize

void BL_RecoveryInitialize()

 

Define the initialization routine for the Debug Catch feature.

 

Location: bl_recovery.h:57

 

BL_SecureBootInitialize

blSecureBootStatus_t BL_SecureBootInitialize()

 

Initialize the Secure Boot subsystem.

 

Location: bl_secure_boot.h:81

 


Return


BL_SEC_NO_ERROR if the initialization is okay, BL_SEC_INIT_FAILED if an error is detected.

 

BL_SecureBootAuthenticate

blSecureBootStatus_t BL_SecureBootAuthenticate(uint32_t opkey1, uint32_t opkey2, uint32_t opcontent, bool verifyImages, uint32_t relocation)

 

Authenticate a RoT certificate chain based on a given RoT.

 

Location: bl_secure_boot.h:95

 

Parameters

Direction Name Description

opkey1

The address of the first key certificate.

opkey2

The address of the second key certificate.

opcontent

The address of a content certificate.

verifyImages

Flag indicating if full verification is to be done.

relocation

The address of the s/w images in memory if not accurate in the content certificate.

 


Return


BL_SEC_NO_ERROR if the authentication passes, suitable error state from blSecureBootStatus_t if an error occurs.

 

BL_FStoreInitialize

BL_FStoreStatus_t BL_FStoreInitialize()

 

Initialize the secure file system.

 

Location: bl_simple_filer.h:110

 


Return


The status of the operation, BL_FS_NO_ERROR if the initialization succeeds.

 

BL_FStoreMakeFilesystem

BL_FStoreStatus_t BL_FStoreMakeFilesystem()

 

Try to make a new file system.

 

Location: bl_simple_filer.h:116

 


Return


BL_FS_NO_ERROR if a new file system can be initialized.

 

BL_FStoreFileSize

uint32_t BL_FStoreFileSize(BL_FSFileId_t id)

 

Retrieve the size in bytes of a requested file.

 

Location: bl_simple_filer.h:123

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


The size in bytes or 65535 if the file cannot be found.

 

BL_FStoreFileExists

bool BL_FStoreFileExists(BL_FSFileId_t id)

 

Determine if the file exists in the store.

 

Location: bl_simple_filer.h:130

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


True if the file exists, false otherwise.

 

BL_FStoreFileCanRead

bool BL_FStoreFileCanRead(BL_FSFileId_t id)

 

Determine if the file exists in the store and can be read.

 

Location: bl_simple_filer.h:137

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


True if the file exists and can be read, false otherwise.

 

BL_FStoreFileCanWrite

bool BL_FStoreFileCanWrite(BL_FSFileId_t id)

 

Determine if the file exists in the store and can be written.

 

Location: bl_simple_filer.h:144

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


True if the file exists and can be written, false otherwise.

 

BL_FStoreFileCanDelete

bool BL_FStoreFileCanDelete(BL_FSFileId_t id)

 

Determine if the file exists in the store and can be deleted.

 

Location: bl_simple_filer.h:151

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


True if the file exists and can be deleted, false otherwise.

 

BL_FStoreWrite

BL_FStoreStatus_t BL_FStoreWrite(BL_FSFileId_t id, uint8_t * buffer, uint16_t size, uint16_t flags)

 

Write a buffer from RAM to the secure file store.

 

Location: bl_simple_filer.h:162

 

Parameters

Direction Name Description

id

The file identifier.

buffer

A pointer to a RAM buffer containing the file contents.

size

The size of the buffer in bytes.

flags

The set of flags associated with the file.

 


Return


BL_FS_NO_ERROR if the file is successfully written, error state otherwise..

 

BL_FStoreRead

BL_FStoreStatus_t BL_FStoreRead(BL_FSFileId_t id, uint8_t * buffer, uint16_t * maxsize)

 

Read a file from the secure file store to a RAM buffer.

 

Location: bl_simple_filer.h:174

 

Parameters

Direction Name Description

id

The file identifier.

buffer

A pointer to a RAM buffer to write the file contents.

maxsize

The maximum size of the buffer in bytes. On exit, this value is updated to reflect the actual number of bytes read.

 


Return


BL_FS_NO_ERROR if the file is successfully read, error state otherwise..

 

BL_FStoreDelete

BL_FStoreStatus_t BL_FStoreDelete(BL_FSFileId_t id)

 

Delete a file from the secure file.

 

Location: bl_simple_filer.h:183

 

Parameters

Direction Name Description

id

The file identifier.

 


Return


BL_FS_NO_ERROR if the file is successfully deleted, error state otherwise..

 

BL_FStoreFileList

BL_FStoreStatus_t BL_FStoreFileList(uint8_t * buffer, uint16_t * maxsize, bool showHidden)

 

Retrieve the secure store directory information.

 

Location: bl_simple_filer.h:194

 

Parameters

Direction Name Description

buffer

A pointer to a RAM buffer to write the directory contents.

maxsize

The maximum size of the buffer in bytes. On exit, this

showHidden

Flag indicating if the reserved files should be included. value is updated to reflect the actual number of bytes read.

 


Return


BL_FS_NO_ERROR if the directory is successfully read, error state otherwise..

 

BL_TargetInitialize

void BL_TargetInitialize()

 

Target initialization function, loads the trim values and sets up the various clocks used in the system.

 

Location: bl_target.h:77

 

BL_TargetReset

void BL_TargetReset()

 

Reset the device using NVIC.

 

Location: bl_target.h:82

 

BL_TickerInitialize

void BL_TickerInitialize()

 

Initialize the timer tick.

 

Location: bl_ticker.h:58

 

BL_TickerTime

uint32_t BL_TickerTime()

 

Get the current timer tick value.

 

Location: bl_ticker.h:64

 


Return


The time since the ticker was initialized in ms.

 

SysTick_Handler

void SysTick_Handler()

 

System tick interrupt handler, required by the ticker.

 

Location: bl_ticker.h:69

 

BL_TraceInitialize

void BL_TraceInitialize()

 

Initialize the trace sub-system.

 

Location: bl_trace.h:70

 

BL_UARTInitialize

void BL_UARTInitialize()

 

Initialize the UART subsystem.

 

Location: bl_uart.h:102

 

BL_UARTReceiveAsync

BL_UARTStatus_t BL_UARTReceiveAsync(uint8_t * buffer, size_t length)

 

Start receiving a fixed length data buffer using the UART.

 

Location: bl_uart.h:119

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_RX_BUSY if another receive operation is currently active.

 

NOTE: No checking is performed to ensure that the buffer is big enough to hold the requested number of bytes. The calling function must ensure this is valid.

NOTE: There must be no pending receive operation pending when this is invoked.

 

BL_UARTReceiveComplete

BL_UARTStatus_t BL_UARTReceiveComplete(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Complete the reception of an executing receive operation.

 

Location: bl_uart.h:137

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

fcs

Indicating if a FCS should be calculated on the input. NULL indicates no FCS calculation needed.

 


Return


BL_UART_NO_ERROR if the operation completes successfully. BL_UART_RX_IDLE if there is no pending receive operation. BL_UART_RX_TIMEOUT if the receive operation timed out. BL_UART_BAD_FCS if the receive operation had an invalid FCS.

 

NOTE: There must be an existing receive operation pending.

NOTE: This is a blocking operation.

 

BL_UARTReceive

BL_UARTStatus_t BL_UARTReceive(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Receiving a fixed length data buffer using the UART.

 

Location: bl_uart.h:161

 

Parameters

Direction Name Description

buffer

A pointer to a buffer in which to store the incoming data.

length

The number of bytes to store in the buffer. (> 0)

fcs

Indicating if a FCS should be calculated on the input. NULL indicates no FCS calculation needed.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_RX_BUSY if another receive operation is currently active. BL_UART_RX_TIMEOUT if the receive operation timed out. BL_UART_BAD_FCS if the receive operation had an invalid FCS.

 

NOTE: No checking is performed to ensure that the buffer is big enough to hold the requested number of bytes. The calling function must ensure this is valid.

NOTE: There must be no pending receive operation pending when this is invoked.

NOTE: This is a blocking operation.

 

BL_UARTSendAsync

BL_UARTStatus_t BL_UARTSendAsync(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Start sending a fixed length data buffer using the UART.

 

Location: bl_uart.h:175

 

Parameters

Direction Name Description

buffer

A pointer to a buffer holding the outgoing data.

length

The number of bytes to send. (> 0)

fcs

The FCS of the buffer to accompany the transmission.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_TX_BUSY if another send operation is currently active.

 

NOTE: There must be no pending transmit operation pending when this is invoked.

 

BL_UARTSendComplete

BL_UARTStatus_t BL_UARTSendComplete()

 

Complete the transmission of an executing send operation.

 

Location: bl_uart.h:188

 


Return


BL_UART_NO_ERROR if the operation completes successfully. BL_UART_TX_IDLE if there is no pending receive operation. BL_UART_TX_TIMEOUT if the send operation timed out.

 

NOTE: There must be an existing transmit operation pending.

NOTE: This is a blocking operation.

 

BL_UARTSend

BL_UARTStatus_t BL_UARTSend(uint8_t * buffer, size_t length, BL_FCS_t * fcs)

 

Send a fixed length data buffer using the UART.

 

Location: bl_uart.h:205

 

Parameters

Direction Name Description

buffer

A pointer to a buffer holding the outgoing data.

length

The number of bytes to send. (> 0)

fcs

The FCS of the buffer to accompany the transmission.

 


Return


BL_UART_NO_ERROR if the operation is started successfully. BL_UART_INVALID_PARAMETER if the length is zero. BL_UART_TX_BUSY if another send operation is currently active. BL_UART_TX_TIMEOUT if the send operation timed out.

 

NOTE: There must be no pending transmit operation pending when this is invoked.

NOTE: This is a blocking operation.

 

BL_UpdateInitialize

void BL_UpdateInitialize()

 

Initialize the firmware update component.

 

Location: bl_update.h:60

 

BL_UpdateRequested

bool BL_UpdateRequested()

 

Check if a firmware update is being requested.

 

Location: bl_update.h:66

 


Return


True if the update pin has been pulled low. False otherwise.

 

BL_UpdateProcessPendingImages

void BL_UpdateProcessPendingImages()

 

This will check for any pending images which have previously been downloaded and if any are found will copy them to the appropriate location for execution.

 

Location: bl_update.h:73

 

BL_ImageSelectAndStartApplication

void BL_ImageSelectAndStartApplication()

 

This will attempt to start any images which are available.

 

This will first try to validate and if necessary authenticate the primary image. If this is successful it will then perform similar validation and authentication on the secondary image. If both the primary and secondary image validation is successful then it will start the secondary image. If only the primary image is valid then it will be started instead. If both the primary and secondary image fail the validation steps then no image will be started and the function will return to the caller and the bootloader will enter the loading state.

 

Location: bl_update.h:90

 

BL_VersionsGetInformation

void BL_VersionsGetInformation(BL_BootAppVersion_t * version, uint32_t address)

 

Get the version information from a suitable application.

 

Location: bl_versions.h:101

 

Parameters

Direction Name Description

version

The structure into which the information should be copied.

address

The base address of the application under consideration.

 

BL_VersionsGetHello

void BL_VersionsGetHello(BL_HelloResponse_t * response)

 

Fetch the hello response from the bootloader.

 

Location: bl_versions.h:108

 

Parameters

Direction Name Description

response

The structure into which the hello response should be copied.

 

BL_WatchdogInitialize

void BL_WatchdogInitialize()

 

Initialise the watchdog module.

 

Location: bl_watchdog.h:64

 

BL_WatchdogSetHoldTime

void BL_WatchdogSetHoldTime(uint32_t seconds)

 

Set the watchdog hold off time to seconds.

 

Location: bl_watchdog.h:76

 

Parameters

Direction Name Description

seconds

The number of seconds to allow before the watchdog bites.

 

NOTE: This allows the watchdog interrupt to fire but refreshes the watchdog itself until the requested number of seconds has elapsed. This is a crude mechanism to prevent long running calculations such as RSA key generation from causing a system reset.

 

WATCHDOG_IRQHandler

void WATCHDOG_IRQHandler()

 

Define an interrupt handler for the watchdog interrupt.

 

Location: bl_watchdog.h:82