Secure Bootloader Sample Reference
Secure Bootloader Sample Reference.
Summary
Typedefs
- BL_FCS_t : Define a FCS type.
- BL_BootAppId_t : Define the application ID as a six character string.
Variables
- 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_UpdateType_t : Define the possible update types.
- BL_ConfigStatus_t : Define the configuration status values.
- BL_FCSStatus_t : Define the possible FCS status values.
- BL_FCSAlgorithm_t : Define the possible valid FCS calculators.
- 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_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.
- 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_KB : Define the size of the bootloader in kB.
- BL_BOOTLOADER_SIZE : The size of the area reserved for use by the bootloader.
- 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_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_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
- 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_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_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_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_RecoveryInitialize : Define the initialization routine for the Debug Catch feature.
- 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:
- Basic bootloader (non-secure)
- Secure bootloader (maintains authenticated Root of Trust set up by the ROM)
- Secure bootloader with secure storage
- Secure bootloader with secure storage and device attestation