IAP_KBP Driver

Overview

Data Structures
struct	_kb_region
	Memory region definition. More...
struct	_kb_load_sb
	User-provided options passed into kb_init(). More...
struct	_memory_region_interface
	Interface to memory operations for one region of memory. More...
struct	_memory_map_entry
	Structure of a memory map entry. More...

Macros
#define	kStatusGroup_RomApi   (108U)
	ROM API status group number.

Typedefs
typedef enum _kb_operation	kb_operation_t
	Details of the operation to be performed by the ROM. More...
typedef struct _kb_region	kb_region_t
	Memory region definition.
typedef struct _kb_load_sb	kb_load_sb_t
	User-provided options passed into kb_init(). More...
typedef struct _memory_region_interface	memory_region_interface_t
	Interface to memory operations for one region of memory.
typedef struct _memory_map_entry	memory_map_entry_t
	Structure of a memory map entry.

Enumerations
enum	{   kStatus_RomApiExecuteCompleted = kStatus_Success,   kStatus_RomApiNeedMoreData,   kStatus_RomApiBufferSizeNotEnough,   kStatus_RomApiInvalidBuffer }
	ROM API status codes. More...
enum	_kb_operation {   kRomAuthenticateImage = 1,   kRomLoadImage = 2 }
	Details of the operation to be performed by the ROM. More...
enum	_kb_security_profile
	Security constraint flags, Security profile flags.

Functions
status_t	kb_init (kb_session_ref_t **session, const kb_options_t *options)
	Initialize ROM API for a given operation. More...
status_t	kb_deinit (kb_session_ref_t *session)
	Cleans up the ROM API context. More...
status_t	kb_execute (kb_session_ref_t *session, const uint8_t *data, uint32_t dataLength)
	Perform the operation configured during init. More...

---

Data Structure Documentation

struct _kb_region

struct _kb_load_sb

The buffer field is a pointer to memory provided by the caller for use by Kboot during execution of the operation. Minimum size is the size of each certificate in the chain plus 432 bytes additional per certificate.

The profile field is a mask that specifies which features are required in the SB file or image being processed. This includes the minimum AES and RSA key sizes. See the _kb_security_profile enum for profile mask constants. The image being loaded or authenticated must match the profile or an error will be returned.

minBuildNumber is an optional field that can be used to prevent version rollback. The API will check the build number of the image, and if it is less than minBuildNumber will fail with an error.

maxImageLength is used to verify the offsetToCertificateBlockHeaderInBytes value at the beginning of a signed image. It should be set to the length of the SB file. If verifying an image in flash, it can be set to the internal flash size or a large number like 0x10000000.

userRHK can optionally be used by the user to override the RHK in IFR. If userRHK is not NULL, it points to a 32-byte array containing the SHA-256 of the root certificate's RSA public key.

The regions field points to an array of memory regions that the SB file being loaded is allowed to access. If regions is NULL, then all memory is accessible by the SB file. This feature is required to prevent a malicious image from erasing good code or RAM contents while it is being loaded, only for us to find that the image is inauthentic when we hit the end of the section.

overrideSBBootSectionID lets the caller override the default section of the SB file that is processed during a kKbootLoadSB operation. By default, the section specified in the firstBootableSectionID field of the SB header is loaded. If overrideSBBootSectionID is non-zero, then the section with the given ID will be loaded instead.

The userSBKEK field lets a user provide their own AES-256 key for unwrapping keys in an SB file during the kKbootLoadSB operation. userSBKEK should point to a 32-byte AES-256 key. If userSBKEK is NULL then the IFR SBKEK will be used. After kb_init() returns, the caller should zero out the data pointed to by userSBKEK, as the API will have installed the key in the CAU3.

struct _memory_region_interface

struct _memory_map_entry

Typedef Documentation

typedef enum _kb_operation kb_operation_t

The kRomAuthenticateImage operation requires the entire signed image to be available to the application.

typedef struct _kb_load_sb kb_load_sb_t

The buffer field is a pointer to memory provided by the caller for use by Kboot during execution of the operation. Minimum size is the size of each certificate in the chain plus 432 bytes additional per certificate.

The profile field is a mask that specifies which features are required in the SB file or image being processed. This includes the minimum AES and RSA key sizes. See the _kb_security_profile enum for profile mask constants. The image being loaded or authenticated must match the profile or an error will be returned.

minBuildNumber is an optional field that can be used to prevent version rollback. The API will check the build number of the image, and if it is less than minBuildNumber will fail with an error.

maxImageLength is used to verify the offsetToCertificateBlockHeaderInBytes value at the beginning of a signed image. It should be set to the length of the SB file. If verifying an image in flash, it can be set to the internal flash size or a large number like 0x10000000.

userRHK can optionally be used by the user to override the RHK in IFR. If userRHK is not NULL, it points to a 32-byte array containing the SHA-256 of the root certificate's RSA public key.

The regions field points to an array of memory regions that the SB file being loaded is allowed to access. If regions is NULL, then all memory is accessible by the SB file. This feature is required to prevent a malicious image from erasing good code or RAM contents while it is being loaded, only for us to find that the image is inauthentic when we hit the end of the section.

overrideSBBootSectionID lets the caller override the default section of the SB file that is processed during a kKbootLoadSB operation. By default, the section specified in the firstBootableSectionID field of the SB header is loaded. If overrideSBBootSectionID is non-zero, then the section with the given ID will be loaded instead.

The userSBKEK field lets a user provide their own AES-256 key for unwrapping keys in an SB file during the kKbootLoadSB operation. userSBKEK should point to a 32-byte AES-256 key. If userSBKEK is NULL then the IFR SBKEK will be used. After kb_init() returns, the caller should zero out the data pointed to by userSBKEK, as the API will have installed the key in the CAU3.

Enumeration Type Documentation

anonymous enum

Enumerator
kStatus_RomApiExecuteCompleted	ROM successfully process the whole sb file/boot image.
kStatus_RomApiNeedMoreData	ROM needs more data to continue processing the boot image.
kStatus_RomApiBufferSizeNotEnough	The user buffer is not enough for use by Kboot during execution of the operation.
kStatus_RomApiInvalidBuffer	The user buffer is not ok for sbloader or authentication.

enum _kb_operation

The kRomAuthenticateImage operation requires the entire signed image to be available to the application.

Enumerator
kRomAuthenticateImage	Authenticate a signed image.
kRomLoadImage	Load SB file.

Function Documentation

status_t kb_init	(	kb_session_ref_t **	session,
		const kb_options_t *	options
	)

Inits the ROM API based on the options provided by the application in the second argument. Every call to rom_init() should be paired with a call to rom_deinit().

Return values

kStatus_Success	API was executed successfully.
kStatus_InvalidArgument	An invalid argument is provided.
kStatus_RomApiBufferSizeNotEnough	The user buffer is not enough for use by Kboot during execution of the operation.
kStatus_RomApiInvalidBuffer	The user buffer is not ok for sbloader or authentication.
kStatus_SKBOOT_Fail	Return the failed status of secure boot.
kStatus_SKBOOT_KeyStoreMarkerInvalid	The key code for the particular PRINCE region is not present in the keystore
kStatus_SKBOOT_Success	Return the successful status of secure boot.

status_t kb_deinit

(

kb_session_ref_t *

session

)

After this call, the context parameter can be reused for another operation by calling rom_init() again.

Return values

kStatus_Success

API was executed successfully

status_t kb_execute	(	kb_session_ref_t *	session,
		const uint8_t *	data,
		uint32_t	dataLength
	)

This application must call this API repeatedly, passing in sequential chunks of data from the boot image (SB file) that is to be processed. The ROM will perform the selected operation on this data and return. The application may call this function with as much or as little data as it wishes, which can be used to select the granularity of time given to the application in between executing the operation.

Parameters

session	Current ROM context pointer.
data	Buffer of boot image data provided to the ROM by the application.
dataLength	Length in bytes of the data in the buffer provided to the ROM.

Return values

kStatus_Success	ROM successfully process the part of sb file/boot image.
kStatus_RomApiExecuteCompleted	ROM successfully process the whole sb file/boot image.
kStatus_Fail	An error occurred while executing the operation.
kStatus_RomApiNeedMoreData	No error occurred, but the ROM needs more data to continue processing the boot image.
kStatus_RomApiBufferSizeNotEnough	user buffer is not enough for use by Kboot during execution of the operation.