IAP_KBP Driver

Overview

Data Structures
struct	kb_region_t
	Memory region definition. More...
struct	kb_load_sb_t
	User-provided options passed into kb_init(). More...
struct	memory_region_interface_t
	Interface to memory operations for one region of memory. More...
struct	memory_map_entry_t
	Structure of a memory map entry. More...

Enumerations
enum	kb_operation_t {   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_t

struct 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.

struct memory_region_interface_t

struct memory_map_entry_t

Enumeration Type Documentation

enum kb_operation_t

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().

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.

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_RomApiExecuteSuccess	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.
kStatus_RomApiBufferNotOkForArena	user buffer does't meet the requirement of arena memory.