# 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:139

## 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:148

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:156

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:173

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:186

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:197

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:120

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:128

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:136

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:149

- 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:165

- 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:177

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:119

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:127

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:125

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:136

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:145

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:112

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:124

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:137

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:147

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:161

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:183

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:196

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:132

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:139

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:120

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:126

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:133

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:142

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:153

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:164

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:175

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:119

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:130

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:140

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:151

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:162

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:168

Return

BL_ENCRYPT_NO_ERROR if success, otherwise error.

## BL_FlashInitialize

void BL_FlashInitialize()

Initialize the flash subsystem.

Location: bl_flash.h:89

## 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:101

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:132

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:141

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:152

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:161

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:169

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:178

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:191

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:201

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:210

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:219

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:226

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:181

## BL_LoaderCertificateAddress

uint32_t BL_LoaderCertificateAddress(BL_LoaderCertType_t cert)

Fetch the address of the requested structure.

Location: bl_loader.h:188

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:106

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:113

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:121

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:128

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:137

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:146

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:154

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:164

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:173

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:181

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:189

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:198

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:91

## BL_SecureBootInitialize

blSecureBootStatus_t BL_SecureBootInitialize()

Initialize the Secure Boot subsystem.

Location: bl_secure_boot.h:114

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:128

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:143

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:149

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:156

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:163

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:170

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:177

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:184

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:195

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:207

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:216

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:227

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:111

## BL_TargetReset

void BL_TargetReset()

Reset the device using NVIC.

Location: bl_target.h:116

## BL_TickerInitialize

void BL_TickerInitialize()

Initialize the timer tick.

Location: bl_ticker.h:92

## BL_TickerTime

uint32_t BL_TickerTime()

Get the current timer tick value.

Location: bl_ticker.h:98

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:103

## BL_TraceInitialize

void BL_TraceInitialize()

Initialize the trace sub-system.

Location: bl_trace.h:100

## BL_UARTInitialize

void BL_UARTInitialize()

Initialize the UART subsystem.

Location: bl_uart.h:136

## 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:153

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:171

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:195

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:209

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:222

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:239

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:94

## BL_UpdateRequested

bool BL_UpdateRequested()

Check if a firmware update is being requested.

Location: bl_update.h:100

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:107

## 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:124

## BL_VersionsGetInformation

void BL_VersionsGetInformation(BL_BootAppVersion_t * version, uint32_t address)

Get the version information from a suitable application.

Location: bl_versions.h:135

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:142

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:97

## BL_WatchdogSetHoldTime

void BL_WatchdogSetHoldTime(uint32_t seconds)

Set the watchdog hold off time to seconds.

Location: bl_watchdog.h:109

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:115