Overview

Data Structures
struct	_nboot_secure_counter
	Data structure holding secure counter value used by nboot library. More...

struct	_nboot_context
	NBOOT context type. More...

struct	_nboot_rot_auth_parms
	NBOOT type for the root of trust parameters. More...

struct	_nboot_sb3_load_manifest_parms
	manifest loading parameters More...

struct	_nboot_img_auth_ecdsa_parms
	Data structure holding input arguments to POR secure boot (authentication) algorithm. More...

struct	_nboot_cmac_authenticate_parms
	Data structure holding input arguments for CMAC authentication. More...

Macros
#define	NXPCLHASH_WA_SIZE_MAX (128U + 64U)
	Define the max workarea size required for this component.

#define	NXPCLCSS_HASH_RTF_OUTPUT_SIZE_HAL ((size_t)32U)
	Size of RTF appendix to hash output buffer, in bytes.

#define	kNBOOT_RootKeyUsage_DebugCA_ImageCA_FwCA_ImageKey_FwKey (0x0U)
	NBOOT type for the root key usage. More...

#define	kNBOOT_RootKey_Enabled (0xAAU)
	NBOOT type for the root key revocation. More...

#define	kNBOOT_RootKey_Ecdsa_P256 (0x0000FE01U)
	NBOOT type specifying the elliptic curve to be used. More...

#define	nboot_lc_nxpBlank (0xFFFF0000U)
	Enumeration for SoC Lifecycle. More...

Typedefs
typedef uint32_t	nboot_status_t
	Type for nboot status codes.

typedef uint64_t	nboot_status_protected_t
	Type for nboot protected status codes.

typedef struct _nboot_secure_counter	nboot_secure_counter_t
	Data structure holding secure counter value used by nboot library.

typedef struct _nboot_context	nboot_context_t
	NBOOT context type. More...

typedef struct _nboot_rot_auth_parms	nboot_rot_auth_parms_t
	NBOOT type for the root of trust parameters. More...

typedef struct _nboot_sb3_load_manifest_parms	nboot_sb3_load_manifest_parms_t
	manifest loading parameters More...

typedef struct _nboot_img_auth_ecdsa_parms	nboot_img_auth_ecdsa_parms_t
	Data structure holding input arguments to POR secure boot (authentication) algorithm. More...

typedef struct _nboot_cmac_authenticate_parms	nboot_img_authenticate_cmac_parms_t
	Data structure holding input arguments for CMAC authentication.

typedef enum _nboot_bool	nboot_bool_t
	Boolean type for the NBOOT functions. More...

Enumerations
enum	{ kStatus_NBOOT_Success = 0x5A5A5A5AU, kStatus_NBOOT_Fail = 0x5A5AA5A5U, kStatus_NBOOT_InvalidArgument = 0x5A5AA5F0U, kStatus_NBOOT_RequestTimeout = 0x5A5AA5E1U, kStatus_NBOOT_KeyNotLoaded = 0x5A5AA5E2U, kStatus_NBOOT_AuthFail = 0x5A5AA5E4U, kStatus_NBOOT_OperationNotAvaialable = 0x5A5AA5E5U, kStatus_NBOOT_KeyNotAvailable = 0x5A5AA5E6U, kStatus_NBOOT_IvCounterOverflow = 0x5A5AA5E7U, kStatus_NBOOT_SelftestFail = 0x5A5AA5E8U, kStatus_NBOOT_InvalidDataFormat = 0x5A5AA5E9U, kStatus_NBOOT_IskCertUserDataTooBig, kStatus_NBOOT_IskCertSignatureOffsetTooSmall, kStatus_NBOOT_MemcpyFail = 0x5A5A845AU }
	nboot status codes. More...

enum	_nboot_bool { kNBOOT_TRUE = 0x3C5AC33CU, kNBOOT_TRUE256 = 0x3C5AC35AU, kNBOOT_TRUE384 = 0x3C5AC3A5U, kNBOOT_FALSE = 0x5AA55AA5U }
	Boolean type for the NBOOT functions. More...

Functions
status_t	NBOOT_GenerateRandom (uint8_t *output, size_t outputByteLen)
	This API function is used to generate random number with specified length. More...

nboot_status_t	NBOOT_ContextInit (nboot_context_t *context)
	The function is used for initializing of the nboot context data structure. More...

nboot_status_t	NBOOT_ContextDeinit (nboot_context_t *context)
	The function is used to deinitialize nboot context data structure. More...

nboot_status_protected_t	NBOOT_Sb3LoadManifest (nboot_context_t context, uint32_t manifest, nboot_sb3_load_manifest_parms_t *params)
	Verify NBOOT SB3.1 manifest (header message) More...

nboot_status_protected_t	NBOOT_Sb3LoadBlock (nboot_context_t context, uint32_t block)
	Verify NBOOT SB3.1 block. More...

nboot_status_protected_t	NBOOT_ImgAuthenticateEcdsa (nboot_context_t context, uint8_t imageStartAddress[], nboot_bool_t isSignatureVerified, nboot_img_auth_ecdsa_parms_t *parms)
	This function authenticates image with asymmetric cryptography. More...

nboot_status_protected_t	NBOOT_ImgAuthenticateCmac (nboot_context_t context, uint8_t imageStartAddress[], nboot_bool_t isSignatureVerified, nboot_img_authenticate_cmac_parms_t *parms)
	This function calculates the CMAC over the given image and compares it to the expected value. More...

Data Structure Documentation

struct _nboot_secure_counter

struct _nboot_context

This type defines the NBOOT context

Data Fields
uint32_t	totalBlocks
	holds number of SB3 blocks. More...

uint32_t	processData
	flag, initialized by nboot_sb3_load_header(). More...

uint32_t	timeout
	timeout value for css operation. More...

uint32_t	keyinfo [NBOOT_KEYINFO_WORDLEN]
	data for NBOOT key management. More...

uint32_t	context [NBOOT_CONTEXT_WORDLEN]
	work area for NBOOT lib. More...

uint32_t	uuid [4]
	holds UUID value from NMPA

uint32_t	prngReadyFlag
	flag, used by nboot_rng_generate_lq_random() to determine whether CSS is ready to generate rnd number

uint32_t	oemShareValidFlag
	flag, used during TP to determine whether valid oemShare was set by nboot_tp_isp_gen_oem_master_share()

uint32_t	oemShare [4]
	buffer to store OEM_SHARE computed by nxpCLTrustProv_nboot_isp_gen_oem_master_share()

nboot_secure_counter_t	secureCounter
	Secure counter used by nboot.

Field Documentation

uint32_t _nboot_context::totalBlocks

Initialized by nboot_sb3_load_header().

uint32_t _nboot_context::processData

SB3 related flag set by NBOOT in case the nboot_sb3_load_block() provides plain data to output buffer (for processing by ROM SB3 loader

uint32_t _nboot_context::timeout

In case it is 0, infinite wait is performed

uint32_t _nboot_context::keyinfo[NBOOT_KEYINFO_WORDLEN]

uint32_t _nboot_context::context[NBOOT_CONTEXT_WORDLEN]

struct _nboot_rot_auth_parms

This type defines the NBOOT root of trust parameters

Data Fields
nboot_root_key_revocation_t	soc_rootKeyRevocation [NBOOT_ROOT_CERT_COUNT]
	Provided by caller based on NVM information in CFPA: ROTKH_REVOKE.

uint32_t	soc_imageKeyRevocation
	Provided by caller based on NVM information in CFPA: IMAGE_KEY_REVOKE.

uint32_t	soc_rkh [12]
	Provided by caller based on NVM information in CMPA: ROTKH (hash of hashes) More...

uint32_t	soc_numberOfRootKeys
	unsigned int, between minimum = 1 and maximum = 4;

nboot_root_key_usage_t	soc_rootKeyUsage [NBOOT_ROOT_CERT_COUNT]
	CMPA.

nboot_root_key_type_and_length_t	soc_rootKeyTypeAndLength
	static selection between ECDSA P-256 or ECDSA P-384 based root keys

Field Documentation

uint32_t _nboot_rot_auth_parms::soc_rkh[12]

In case of kNBOOT_RootKey_Ecdsa_P384, sock_rkh[0..11] are used In case of kNBOOT_RootKey_Ecdsa_P256, sock_rkh[0..7] are used

struct _nboot_sb3_load_manifest_parms

This type defines the NBOOT SB3.1 manifest loading parameters

Data Fields
nboot_rot_auth_parms_t	soc_RoTNVM
	trusted information originated from CFPA and NMPA

uint32_t	soc_trustedFirmwareVersion
	Provided by caller based on NVM information in CFPA: Secure_FW_Version.

struct _nboot_img_auth_ecdsa_parms

Shall be read from SoC trusted NVM or SoC fuses.

Data Fields
nboot_rot_auth_parms_t	soc_RoTNVM
	trusted information originated from CFPA and NMPA

uint32_t	soc_trustedFirmwareVersion
	Provided by caller based on NVM information in CFPA: Secure_FW_Version.

struct _nboot_cmac_authenticate_parms

Data Fields
uint32_t	expectedMAC [4]
	expected MAC result

Macro Definition Documentation

#define kNBOOT_RootKeyUsage_DebugCA_ImageCA_FwCA_ImageKey_FwKey (0x0U)

This type defines the NBOOT root key usage; any other value means the root key is not valid (treat as if revoked).

#define kNBOOT_RootKey_Enabled (0xAAU)

This type defines the NBOOT root key revocation; any other value means the root key is revoked.

#define kNBOOT_RootKey_Ecdsa_P256 (0x0000FE01U)

This type defines the elliptic curve type and length

#define nboot_lc_nxpBlank (0xFFFF0000U)

Typedef Documentation

typedef struct _nboot_context nboot_context_t

This type defines the NBOOT context

typedef struct _nboot_rot_auth_parms nboot_rot_auth_parms_t

This type defines the NBOOT root of trust parameters

typedef struct _nboot_sb3_load_manifest_parms nboot_sb3_load_manifest_parms_t

This type defines the NBOOT SB3.1 manifest loading parameters

typedef struct _nboot_img_auth_ecdsa_parms nboot_img_auth_ecdsa_parms_t

Shall be read from SoC trusted NVM or SoC fuses.

typedef enum _nboot_bool nboot_bool_t

This type defines boolean values used by NBOOT functions that are not easily disturbed by Fault Attacks

Enumeration Type Documentation

anonymous enum

Enumerator
kStatus_NBOOT_Success	Operation completed successfully.
kStatus_NBOOT_Fail	Operation failed.
kStatus_NBOOT_InvalidArgument	Invalid argument passed to the function.
kStatus_NBOOT_RequestTimeout	Operation timed out.
kStatus_NBOOT_KeyNotLoaded	The requested key is not loaded.
kStatus_NBOOT_AuthFail	Authentication failed.
kStatus_NBOOT_OperationNotAvaialable	Operation not available on this HW.
kStatus_NBOOT_KeyNotAvailable	Key is not avaialble.
kStatus_NBOOT_IvCounterOverflow	Overflow of IV counter (PRINCE/IPED).
kStatus_NBOOT_SelftestFail	FIPS self-test failure.
kStatus_NBOOT_InvalidDataFormat	Invalid data format for example antipole.
kStatus_NBOOT_IskCertUserDataTooBig	Size of User data in ISK certificate is greater than 96 bytes.
kStatus_NBOOT_IskCertSignatureOffsetTooSmall	Signature offset in ISK certificate is smaller than expected.
kStatus_NBOOT_MemcpyFail	Unexpected error detected during nboot_memcpy()

enum _nboot_bool

This type defines boolean values used by NBOOT functions that are not easily disturbed by Fault Attacks

Enumerator
kNBOOT_TRUE	Value for TRUE.
kNBOOT_TRUE256	Value for TRUE when P256 was used to sign the image.
kNBOOT_TRUE384	Value for TRUE when P384 was used to sign the image.
kNBOOT_FALSE	Value for FALSE.

Function Documentation

status_t NBOOT_GenerateRandom	(	uint8_t *	output,
		size_t	outputByteLen
	)

Parameters

output	Pointer to random number buffer
outputByteLen	length of generated random number in bytes. Length has to be in range <1, 2^16>

Return values

kStatus_NBOOT_InvalidArgument	Invalid input parameters (Input pointers points to NULL or length is invalid)
kStatus_NBOOT_Success	Operation successfully finished
kStatus_NBOOT_Fail	Error occured during operation

nboot_status_t NBOOT_ContextInit ( nboot_context_t * context )

   It should be called prior to any other calls of nboot API.

Parameters

context Pointer to nboot_context_t structure.

Return values

kStatus_NBOOT_Success	Operation successfully finished
kStatus_NBOOT_Fail	Error occured during operation

nboot_status_t NBOOT_ContextDeinit ( nboot_context_t * context )

Its contents are overwritten with random data so that any sensitive data does not remain in memory.

Parameters

context Pointer to nboot_context_t structure.

Return values

kStatus_NBOOT_Success	Operation successfully finished
kStatus_NBOOT_Fail	Error occured during operation

nboot_status_protected_t NBOOT_Sb3LoadManifest	(	nboot_context_t *	context,
		uint32_t *	manifest,
		nboot_sb3_load_manifest_parms_t *	params
	)

This function verifies the NBOOT SB3.1 manifest (header message), initializes the context and loads keys into the CSS key store so that they can be used by nboot_sb3_load_block function. The NBOOT context has to be initialized by the function nboot_context_init before calling this function. Please note that this API is intended to be used only by users who needs to split FW update process (loading of SB3.1 file) to partial steps to customize whole operation. For regular SB3.1 processing, please use API described in chapter SBloader APIs.

Parameters

context	Pointer to nboot_context_t structure.
manifest	Pointer to the input manifest buffer
params	additional input parameters. Please refer to nboot_sb3_load_manifest_parms_t definition for details.

Return values

kStatus_NBOOT_Success	Operation successfully finished
kStatus_NBOOT_Fail	Error occured during operation

nboot_status_protected_t NBOOT_Sb3LoadBlock	(	nboot_context_t *	context,
		uint32_t *	block
	)

This function verifies and decrypts an NBOOT SB3.1 block. Decryption is performed in-place. The NBOOT context has to be initialized by the function nboot_context_init before calling this function. Please note that this API is intended to be used only by users who needs to split FW update process (loading of SB3.1 file) to partial steps to customize whole operation. For regular SB3.1 processing, please use API described in chapter SBloader APIs.

Parameters

context	Pointer to nboot_context_t structure.
block	Pointer to the input SB3.1 data block

Return values

kStatus_NBOOT_Success	successfully finished
kStatus_NBOOT_Fail	occured during operation

nboot_status_protected_t NBOOT_ImgAuthenticateEcdsa	(	nboot_context_t *	context,
		uint8_t	imageStartAddress[],
		nboot_bool_t *	isSignatureVerified,
		nboot_img_auth_ecdsa_parms_t *	parms
	)

   The NBOOT context has to be initialized by the function nboot_context_init
   before calling this function.

Parameters

context	Pointer to nboot_context_t structure.
imageStartAddress	Pointer to start of the image in memory.
isSignatureVerified	Pointer to memory holding function call result. After the function returns, the value will be set to kNBOOT_TRUE when the image is authentic. Any other value means the authentication does not pass.
parms	Pointer to a data structure in trusted memory, holding input parameters for the algorithm. The data structure shall be correctly filled before the function call.

Return values

kStatus_NBOOT_Success	Operation successfully finished
kStatus_NBOOT_Fail	Returned in all other cases. Doesn't always mean invalid image, it could also mean transient error caused by short time environmental conditions.

nboot_status_protected_t NBOOT_ImgAuthenticateCmac	(	nboot_context_t *	context,
		uint8_t	imageStartAddress[],
		nboot_bool_t *	isSignatureVerified,
		nboot_img_authenticate_cmac_parms_t *	parms
	)

To be more resistant against SPA, it is recommended that imageStartAddress is word aligned. The NBOOT context has to be initialized by the nboot_context_init() before calling this function.

Parameters

context	Pointer to nboot_context_t structure.
imageStartAddress	Pointer to start of the image in memory.
isSignatureVerified	Pointer to memory holding function call result. After the function returns, the value will be set to
parms	Pointer to a data structure in trusted memory, holding the reference MAC. The data structure shall be correctly filled before the function call.

Return values

kStatus_NBOOT_Success
kStatus_NBOOT_Fail

Overview

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Data Fields

Data Fields

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation