# Secure Bootloader Sample Reference

Secure Bootloader Sample Reference.

# Summary

Typedefs

- BL_FCS_t : Define a FCS type.
- BL_FSFileId_t : Define a file identifier as a sixteen bit word.
- BL_BootAppId_t : Define the application ID as a six character string.

Variables

- DRBGContext : Define a CTR_DRBG context structure, used by the RNDContext.
- BL_ImageWorkspace : Defines a common operation buffer for handling images.

Data Structures

- BL_AppConfiguration_t : Define a structure which can map onto the configuration area.
- BL_ImageOperation_t : Buffer used for loading data in chunks, allow 2 blocks.
- BL_ImageSplitRange_t : define an address range which can wrap-around a reserved block
- BL_StatusResponse_t : to maintain backwards compatibility, we use a two byte status for most messages.
- BL_BootAppVersion_t : Define the application version as id and version details.
- BL_HelloResponse_t : Define the contents of a Hello response.

Enumerations

- BL_AttestStatus_t : Define the basic attestation status types.
- BL_AttestKeyType_t : Define the types of attestation keys supported by the system.
- BL_AttestationChallengeSize_t : Define the supported attestation challenge sizes.
- BL_AttestTags_t : Define CBOR tag values for each of the attestation fields.
- BL_UpdateType_t : Define the possible update types.
- BL_ConfigStatus_t : Define the configuration status values.
- BL_CryptoStatus_t : Define the status values returned by the cryptography modules.
- BL_CryptoRSAKeyType_t : Define the supported key types, encoding the key size in bits.
- BL_EATStatus_t : Define the possible status codes.
- BL_EATTags_t : Define CBOR tag values for each of the EAT fields.
- BL_FCSStatus_t : Define the possible FCS status values.
- BL_FCSAlgorithm_t : Define the possible valid FCS calculators.
- BL_EncryptionStatus_t : Define the file encryption status values.
- BL_ImageType_t : Define the known image types.
- BL_ImageStatus_t : Define the image status values.
- BL_LoaderCommand_t : Enum specifying each of the valid commands the loader recognizes.
- BL_LoaderStatus_t : Define a set of supported loader status codes.
- BL_LoaderCertType_t : Enum specifying the types of certificate that can be loaded.
- BL_LoaderStatusType_t : Define a type for the status messages.
- BL_CBORStatus_t : Define the CBOR status values.
- blSecureBootStatus_t : Define the status codes.
- BL_FStoreStatus_t : Define the status values possible from the secure filer module.
- BL_FSFlags_t : Define the flags associated with stored files.
- BL_FSReservedFilename_t : Define a set of reserved file names that should not be accessible directly from the loader.
- BL_UARTStatus_t : Define a set of supported error codes.

Macros

- VT_OFFSET_STACK_POINTER : Vector table offset for the stack pointer.
- VT_OFFSET_RESET_VECTOR : Vector table offset for the reset vector.
- VT_OFFSET_VERSION_INFO : Vector table offset for the version information pointer.
- VT_OFFSET_IMAGE_SIZE : Vector table offset for the used image size pointer.
- VT_OFFSET_CERT_SIZE : Vector table offset for the certificate size.
- BL_CONFIGURATION_BASE : Base address of the boot configuration in flash.
- BL_CONFIGURATION_WORDS : Define the size of the configuration area in words.
- BL_CRYPTO_BOOT_SEED_LENGTH : Define the length in bytes of the boot seed value, random number.
- BL_CRYPTO_SHA256_DIGEST_LENGTH : Define the digest length in bytes for SHA256.
- BL_ENCRYPT_KEY_SIZE_BITS : Define the AES key size in bits when performing AES encryption.
- BL_ENCRYPT_KEY_SIZE_BYTES : Define the AES key size in bytes when performing AES encryption.
- BL_ENCRYPT_BLOCK_SIZE_BITS : Define the block size in bits when performing AES encryption.
- BL_ENCRYPT_BLOCK_SIZE_BYTES : Define the block size in bytes when performing AES encryption.
- FLASH_BOND_INFO_SIZE
- BL_CODE_SECTOR_SIZE : The image block size when loading data.
- BL_DATA_SECTOR_SIZE : The image block size when loading data.
- BL_FLASH_RESERVED_SIZE : The size of the area reserved for use by the ROM and stack.
- BL_SECURE_STORAGE_BASE : Define the base address of the secure storage area.
- BL_SECURE_STORAGE_SIZE : Define a size for the secure storage area.
- BL_SECURE_STORAGE_TOP : Define the top of the secure storage area.
- BL_BOOTLOADER_BASE : The base address of the bootloader flash.
- BL_BOOTLOADER_SIZE : Define the size of the bootloader in kB.
- BL_FLASH_CODE_BASE : The base of the code flash.
- BL_FLASH_DATA_BASE : The base of the data flash, offset by the reserved areas.
- BL_FLASH_CODE_TOP : Define the top of code flash in 512K device.
- BL_FLASH_DATA_TOP : Define the top of data flash in 512K device.
- BL_FLASH_CODE_SIZE : Code size is derived from the base and top addresses.
- BL_FLASH_DATA_SIZE : Data size is derived from the base and top addresses.
- BL_APPLICATION_BASE : Define the base address of the application.
- BL_AVAILABLE_SIZE : Define the total available flash for application and download.
- BL_APPLICATION_SIZE : Define the maximum size of an application.
- BL_DOWNLOAD_BASE : Define the base address of the download area.
- BL_DOWNLOAD_SIZE : Define the maximum size of the download area.
- BL_OPT_FEATURE_ENABLED : Indicator that a given feature should be enabled.
- BL_OPT_FEATURE_DISABLED : Indicator that a given features should be disabled.
- BL_OPT_FEATURE_BOOTLOADER : Marker indicating that the bootloader feature is enabled.
- BL_OPT_FEATURE_BOOTLOADER : Marker indicating that the bootloader feature is enabled.
- BL_OPT_FEATURE_SECURE_BOOTLOADER : Marker indicating that the bootloader supports authenticated update of images.
- BL_OPT_FEATURE_SECURE_BOOTLOADER : Marker indicating that the bootloader supports authenticated update of images.
- BL_OPT_FEATURE_SECURE_STORAGE : Marker indicating if the secure storage feature is provided.
- BL_OPT_FEATURE_SECURE_STORAGE : Marker indicating if the secure storage feature is provided.
- BL_OPT_FEATURE_ATTESTATION : Marker indicating if the bootloader supports attestation protocols.
- BL_OPT_ATTEST_KEY_AES : Marker indicating that the attestation feature supports AES keys.
- BL_OPT_ATTEST_KEY_RSA : Marker indicating that the attestation feature supports RSA keys.
- BL_OPT_ATTEST_KEY_ECC : Marker indicating that the attestation feature supports ECC keys.
- BL_OPT_SECURE_FILE_SYSTEM_RESET : Marker indicating that the attestation feature supports AES keys.
- DEBUG_CATCH_GPIO
- BL_SEC_IGNORE_KEY : Define a marker value that indicates a key may be ignored.
- BL_SEC_DEFER_KEY : Define a marker value that indicates a key should be deferred.
- BL_FS_MAX_FILE_SIZE : Define the maximum supported file size.
- UART_CLK : Set UART peripheral clock.
- SENSOR_CLK : Set sensor clock.
- USER_CLK : Set user clock.
- VCC_BUCK_ENABLE : Enable or disable the buck converter.
- BL_TICKER_TIME_MS : Define the time in ms for each interrupt.
- BL_DEBUG : Define the standard verbose/debug tracing routine.
- BL_TRACE : Define the standard tracing routine.
- BL_WARNING : Define the standard warning message routine.
- BL_ERROR : Define the standard error message routine.
- BL_UART_RX_TIMEOUT_MS : Define the receive timeout in milliseconds.
- BL_WATCHDOG_FEED_ME_MS : While waiting for UART input, ensure watch dog is fed.
- BL_UART_TX_TIMEOUT_MS : Define the send timeout in milliseconds.
- BL_UART_MAX_RX_LENGTH : Define the maximum length of a single receive operation.
- BL_UART_MAX_TX_LENGTH : Define the maximum length of a single send operation.
- BL_BAUD_RATE : Define a baud rate for loading.
- BL_UART_DELAY_CYCLES : Define a delay time to allow the hardware buffers to clear.
- UPDATE_GPIO : Define the GPIO pin to be used to indicate an update is required.
- MIN : Define a shorthand to get the minimum of two values.
- MAX : Define a shorthand to get the maximum of two values.
- BITS2BYTES : Calculate the number of bytes needed to hold x bits.
- BITS2HALFWORDS : Calculate the number of 16 bit words needed to hold x bits.
- BL_VERSION_ENCODE : Define a mechanism to encode a version number as a uint16_t.
- BL_VERSION_DECODE : Define a mechanism to decode a version number from a uint16_t.
- BL_BOOT_VERSION : Define the boot version including name and ensure it is stored in an easily accessible location.
- BL_WATCHDOG_MAX_HOLD_OFF_SECONDS : Define the maximum time that can elapse before the watchdog must be refreshed.

Functions

- BL_AttestInitialize : Initialize the attestation feature.
- BL_AttestAcceptKey : Determine if it is okay to accept a key injection request.
- BL_AttestFindPublicKeyHash : Retrieve the SHA256 hash of the public key if it exists.
- BL_AttestInjectKey : Inject or create an attestation key.
- BL_AttestGetToken : return the Entity Attestation Token associated with the device.
- BL_AttestGetTokenSize : return the size of the Entity Attestation Token associated with the device.
- BL_CheckRemapAddressSpace : Determine download address based on given address which may be in bootloader or application space.
- BL_CheckGetApplicationSize : Fetch the application size from a buffer defined by base address of the application vector table.
- BL_CheckRelocatedApplicationSize : Fetch the application size from a buffer defined by base address of the application vector table.
- BL_CheckIfImageUpdateAvailable : Check for a valid update using the non-secure file format.
- BL_CheckIfSecureImageUpdateAvailable : Check for a valid update using the secure file format.
- BL_CheckFindSecondaryImageLocation : Based on a primary image address, calculate the potential location and extent of any secondary image.
- BL_ConfigIsValid : Helper function to return the configuration area status.
- BL_ConfigCertificateAddress : Fetch the address of the requested structure.
- BL_CryptoInitialize : Initialize the basic crypto system.
- BL_CryptoGetBootSeed : Fetch the boot seed.
- BL_CryptoHash : Hash a block of memory using SHA256.
- BL_CryptoRSAKeySize : Calculate the size required to serialize a given RSA private key.
- BL_CryptoRSASerialiseKey : Serialize an RSA key to a byte buffer.
- BL_CryptoRSADeserialiseKey : Deserialize an RSA key from a byte buffer.
- BL_CryptoRSAGenerateKey : Generate a new RSA key of the given type.
- BL_CryptoRSASignHash : Sign a message hash using a private RSA key.
- BL_CryptoRSASignMessage : Sign a message using a private RSA key.
- BL_CryptoRSAVerifyMessage : Verify that a given hash and signature are consistent.
- BL_EATPopulate : Populates a buffer with the contents of the entity attestation token.
- BL_EATSize : Calculate the expected size of the EAT token once converted to CBOR.
- BL_FCSInitialize : Initialize the FCS module, deriving the selected algorithm from the provided sample data.
- BL_FCSQuery : Query the currently selected FCS algorithm.
- BL_FCSAuthenticationRequired : Provides a mechanism to determine if the loading process should apply authentication to the protocol and images.
- BL_FCSSelect : Select a specific FCS algorithm.
- BL_FCSCheck : Check the validity of a buffer against a given FCS.
- BL_FCSCalculate : Calculate the FCS of a given buffer.
- BL_FCSAccumulateCRC : Helper method to accumulate a CRC given a buffer and a length.
- BL_EncryptInitialize : Initialization function for the encryption layer.
- BL_EncryptResetEncryption : Reset the encryption operation and introduce a new initial value.
- BL_EncryptResetDecryption : Reset the decryption operation and introduce a new initial value.
- BL_EncryptEncryptBuffer : Encrypt a buffer using the internally derived key.
- BL_EncryptDecryptBuffer : Decrypt a buffer using the internally derived key.
- BL_EncryptComplete : Complete the current encryption or decryption operation.
- BL_FlashInitialize : Initialize the flash subsystem.
- BL_FlashSaveSector : Save a buffer to a specified flash address.
- BL_ImageInitialize : Initialize the image module for a specific set of image attributes.
- BL_ImageAddress : Convert an address to take into account potential offsets.
- BL_ImageAddressRange : Helper routine which allows access of the image as a contiguous block of addresses, wrapping around the reserved block.
- BL_ImageCopyMemoryRange : Copy a possibly split memory range to a contiguous buffer.
- BL_ImageSaveBlock : Save a block of data from a RAM buffer to the next block in Flash.
- BL_ImageVerify : Verify the most recently loaded image.
- BL_ImageAuthenticate : Authenticate a loaded image.
- BL_ImageAuthenticateCurrent : Authenticate the most recently loaded image.
- BL_ImageIsValid : Check if there is a valid image to start.
- BL_ImageSaveAddress : Return the download address corresponding to the requested address.
- BL_ImageStartApplication : Start the image stored in flash.
- BL_LoaderPerformFirmwareLoad : Perform a firmware update over the UART interface.
- BL_LoaderCertificateAddress : Fetch the address of the requested structure.
- BL_CBORInitialize : Initialize the CBOR renderer giving it a buffer to render to.
- BL_CBORReset : Reset the CBOR renderer pointers to the initial state.
- BL_CBORUsed : Provide an indication of the amount of the buffer that has been used.
- BL_CBORCurrent : Retrieve the current pointer onto the render buffer.
- BL_CBORAddInteger : Add an integer to the CBOR buffer.
- BL_CBORAddBuffer : Add a fixed size buffer to the CBOR buffer.
- BL_CBORAddMap : Add a map with a fixed number of entries to the CBOR buffer.
- BL_CBORAddMapPair : Add a key value pair to a map.
- BL_CBORSizeInteger : Retrieve the rendered size of an integer value.
- BL_CBORSizeBuffer : Retrieve the rendered size of a buffer.
- BL_CBORSizeMap : Retrieve the number of bytes in a rendered map header.
- BL_CBORSizeMapPair : Retrieve the rendered size of a key value pair.
- BL_RecoveryInitialize : Define the initialization routine for the Debug Catch feature.
- BL_SecureBootInitialize : Initialize the Secure Boot subsystem.
- BL_SecureBootAuthenticate : Authenticate a RoT certificate chain based on a given RoT.
- BL_FStoreInitialize : Initialize the secure file system.
- BL_FStoreMakeFilesystem : Try to make a new file system.
- BL_FStoreFileSize : Retrieve the size in bytes of a requested file.
- BL_FStoreFileExists : Determine if the file exists in the store.
- BL_FStoreFileCanRead : Determine if the file exists in the store and can be read.
- BL_FStoreFileCanWrite : Determine if the file exists in the store and can be written.
- BL_FStoreFileCanDelete : Determine if the file exists in the store and can be deleted.
- BL_FStoreWrite : Write a buffer from RAM to the secure file store.
- BL_FStoreRead : Read a file from the secure file store to a RAM buffer.
- BL_FStoreDelete : Delete a file from the secure file.
- BL_FStoreFileList : Retrieve the secure store directory information.
- BL_TargetInitialize : Target initialization function, loads the trim values and sets up the various clocks used in the system.
- BL_TargetReset : Reset the device using NVIC.
- BL_TickerInitialize : Initialize the timer tick.
- BL_TickerTime : Get the current timer tick value.
- SysTick_Handler : System tick interrupt handler, required by the ticker.
- BL_TraceInitialize : Initialize the trace sub-system.
- BL_UARTInitialize : Initialize the UART subsystem.
- BL_UARTReceiveAsync : Start receiving a fixed length data buffer using the UART.
- BL_UARTReceiveComplete : Complete the reception of an executing receive operation.
- BL_UARTReceive : Receiving a fixed length data buffer using the UART.
- BL_UARTSendAsync : Start sending a fixed length data buffer using the UART.
- BL_UARTSendComplete : Complete the transmission of an executing send operation.
- BL_UARTSend : Send a fixed length data buffer using the UART.
- BL_UpdateInitialize : Initialize the firmware update component.
- BL_UpdateRequested : Check if a firmware update is being requested.
- 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.
- BL_ImageSelectAndStartApplication : This will attempt to start any images which are available.
- BL_VersionsGetInformation : Get the version information from a suitable application.
- BL_VersionsGetHello : Fetch the hello response from the bootloader.
- BL_WatchdogInitialize : Initialise the watchdog module.
- BL_WatchdogSetHoldTime : Set the watchdog hold off time to seconds.
- WATCHDOG_IRQHandler : Define an interrupt handler for the watchdog interrupt.

# Detailed Description

This reference chapter presents a detailed description of all the components included in the secure bootloader reference application. This reference application has four levels of secure operation, available as needed depending on the end product's use cases:

1. Basic bootloader (non-secure)
2. Secure bootloader (maintains authenticated Root of Trust set up by the ROM)
3. Secure bootloader with secure storage
4. Secure bootloader with secure storage and device attestation