Overview

The MCUXpresso SDK provides a peripheral driver for the PRINCE bus crypto engine module of MCUXpresso SDK devices.

..

This example code shows how to use the PRINCE driver.

Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/prince

Typedefs
typedef enum _skboot_status	skboot_status_t
	Secure status enumeration. More...

typedef enum _secure_bool	secure_bool_t
	Secure boolean enumeration. More...

typedef enum _prince_region	prince_region_t
	Prince region. More...

typedef enum _prince_lock	prince_lock_t
	Prince lock. More...

typedef enum _prince_flags	prince_flags_t
	Prince flag. More...

Enumerations
enum	_skboot_status { kStatus_SKBOOT_Success = 0x5ac3c35au, kStatus_SKBOOT_Fail = 0xc35ac35au, kStatus_SKBOOT_InvalidArgument = 0xc35a5ac3u, kStatus_SKBOOT_KeyStoreMarkerInvalid = 0xc3c35a5au, kStatus_SKBOOT_HashcryptFinishedWithStatusSuccess, kStatus_SKBOOT_HashcryptFinishedWithStatusFail, kStatus_SKBOOT_Success = 0x5ac3c35au, kStatus_SKBOOT_Fail = 0xc35ac35au, kStatus_SKBOOT_InvalidArgument = 0xc35a5ac3u, kStatus_SKBOOT_KeyStoreMarkerInvalid = 0xc3c35a5au }
	Secure status enumeration. More...

enum	_secure_bool { kSECURE_TRUE = 0xc33cc33cU, kSECURE_FALSE = 0x5aa55aa5U, kSECURE_CALLPROTECT_SECURITY_FLAGS = 0xc33c5aa5U, kSECURE_CALLPROTECT_IS_APP_READY = 0x5aa5c33cU, kSECURE_TRACKER_VERIFIED = 0x55aacc33U, kSECURE_TRUE = 0xc33cc33cU, kSECURE_FALSE = 0x5aa55aa5U }
	Secure boolean enumeration. More...

enum	_prince_region { kPRINCE_Region0 = 0U, kPRINCE_Region1 = 1U, kPRINCE_Region2 = 2U }
	Prince region. More...

enum	_prince_lock { kPRINCE_Region0Lock = 1U, kPRINCE_Region1Lock = 2U, kPRINCE_Region2Lock = 4U, kPRINCE_MaskLock = 256U }
	Prince lock. More...

enum	_prince_flags { kPRINCE_Flag_None = 0U, kPRINCE_Flag_EraseCheck = 1U, kPRINCE_Flag_WriteCheck = 2U }
	Prince flag. More...

Functions
static void	PRINCE_EncryptEnable (PRINCE_Type *base)
	Enable data encryption. More...

static void	PRINCE_EncryptDisable (PRINCE_Type *base)
	Disable data encryption. More...

static bool	PRINCE_IsEncryptEnable (PRINCE_Type *base)
	Is Enable data encryption. More...

static void	PRINCE_SetMask (PRINCE_Type *base, uint64_t mask)
	Sets PRINCE data mask. More...

static void	PRINCE_SetLock (PRINCE_Type *base, uint32_t lock)
	Locks access for specified region registers or data mask register. More...

status_t	PRINCE_GenNewIV (prince_region_t region, uint8_t iv_code, bool store, flash_config_t flash_context)
	Generate new IV code. More...

status_t	PRINCE_LoadIV (prince_region_t region, uint8_t *iv_code)
	Load IV code. More...

status_t	PRINCE_SetEncryptForAddressRange (prince_region_t region, uint32_t start_address, uint32_t length, flash_config_t *flash_context, bool regenerate_iv)
	Allow encryption/decryption for specified address range. More...

status_t	PRINCE_GetRegionSREnable (PRINCE_Type base, prince_region_t region, uint32_t sr_enable)
	Gets the PRINCE Sub-Region Enable register. More...

status_t	PRINCE_GetRegionBaseAddress (PRINCE_Type base, prince_region_t region, uint32_t region_base_addr)
	Gets the PRINCE region base address register. More...

status_t	PRINCE_SetRegionIV (PRINCE_Type *base, prince_region_t region, const uint8_t iv[8])
	Sets the PRINCE region IV. More...

status_t	PRINCE_SetRegionBaseAddress (PRINCE_Type *base, prince_region_t region, uint32_t region_base_addr)
	Sets the PRINCE region base address. More...

status_t	PRINCE_SetRegionSREnable (PRINCE_Type *base, prince_region_t region, uint32_t sr_enable)
	Sets the PRINCE Sub-Region Enable register. More...

status_t	PRINCE_FlashEraseWithChecker (flash_config_t *config, uint32_t start, uint32_t lengthInBytes, uint32_t key)
	Erases the flash sectors encompassed by parameters passed into function. More...

status_t	PRINCE_FlashProgramWithChecker (flash_config_t config, uint32_t start, uint8_t src, uint32_t lengthInBytes)
	Programs flash with data at locations passed in through parameters. More...

Driver version
#define	FSL_PRINCE_DRIVER_VERSION (MAKE_VERSION(2, 6, 0))
	PRINCE driver version 2.6.0. More...

Macro Definition Documentation

#define FSL_PRINCE_DRIVER_VERSION (MAKE_VERSION(2, 6, 0))

Current version: 2.6.0

Change log:

Version 2.0.0
- Initial version.
Version 2.1.0
- Update for the A1 rev. of LPC55Sxx serie.
Version 2.2.0
- Add runtime checking of the A0 and A1 rev. of LPC55Sxx serie to support both silicone revisions.
Version 2.3.0
- Add support for LPC55S1x and LPC55S2x series
Version 2.3.0
- Fix MISRA-2012 issues.
Version 2.3.1
- Add support for LPC55S0x series
Version 2.3.2
- Fix documentation of enumeration. Extend PRINCE example.
Version 2.4.0
- Add support for LPC55S3x series
Version 2.5.0
- Add PRINCE_Config() and PRINCE_Reconfig() features.
Version 2.5.1
- Fix build error due to renamed symbols
Version 2.6.0
- Renamed CSS to ELS

Typedef Documentation

typedef enum _skboot_status skboot_status_t

typedef enum _secure_bool secure_bool_t

typedef enum _prince_region prince_region_t

typedef enum _prince_lock prince_lock_t

typedef enum _prince_flags prince_flags_t

Enumeration Type Documentation

enum _skboot_status

Enumerator
kStatus_SKBOOT_Success	SKBOOT return success status.
kStatus_SKBOOT_Fail	SKBOOT return fail status.
kStatus_SKBOOT_InvalidArgument	SKBOOT return invalid argument status.
kStatus_SKBOOT_KeyStoreMarkerInvalid	SKBOOT return Keystore invalid Marker status.
kStatus_SKBOOT_HashcryptFinishedWithStatusSuccess	SKBOOT return Hashcrypt finished with the success status.
kStatus_SKBOOT_HashcryptFinishedWithStatusFail	SKBOOT return Hashcrypt finished with the fail status.
kStatus_SKBOOT_Success	PRINCE Success.
kStatus_SKBOOT_Fail	PRINCE Fail.
kStatus_SKBOOT_InvalidArgument	PRINCE Invalid argument.
kStatus_SKBOOT_KeyStoreMarkerInvalid	PRINCE Invalid marker.

enum _secure_bool

Enumerator
kSECURE_TRUE	Secure true flag.
kSECURE_FALSE	Secure false flag.
kSECURE_CALLPROTECT_SECURITY_FLAGS	Secure call protect the security flag.
kSECURE_CALLPROTECT_IS_APP_READY	Secure call protect the app is ready flag.
kSECURE_TRACKER_VERIFIED	Secure tracker verified flag.
kSECURE_TRUE	PRINCE true.
kSECURE_FALSE	PRINCE false.

enum _prince_region

Enumerator
kPRINCE_Region0	PRINCE region 0.
kPRINCE_Region1	PRINCE region 1.
kPRINCE_Region2	PRINCE region 2.

enum _prince_lock

Enumerator
kPRINCE_Region0Lock	PRINCE region 0 lock.
kPRINCE_Region1Lock	PRINCE region 1 lock.
kPRINCE_Region2Lock	PRINCE region 2 lock.
kPRINCE_MaskLock	PRINCE mask register lock.

enum _prince_flags

Enumerator
kPRINCE_Flag_None	PRINCE Flag None.
kPRINCE_Flag_EraseCheck	PRINCE Flag Erase check.
kPRINCE_Flag_WriteCheck	PRINCE Flag Write check.

Function Documentation

static void PRINCE_EncryptEnable ( PRINCE_Type * base )

inlinestatic

This function enables PRINCE on-the-fly data encryption.

Parameters

base	PRINCE peripheral address.

static void PRINCE_EncryptDisable ( PRINCE_Type * base )

inlinestatic

This function disables PRINCE on-the-fly data encryption.

Parameters

base	PRINCE peripheral address.

static bool PRINCE_IsEncryptEnable ( PRINCE_Type * base )

inlinestatic

This function test if PRINCE on-the-fly data encryption is enabled.

Parameters

base	PRINCE peripheral address.

Returns: true if enabled, false if not

static void PRINCE_SetMask	(	PRINCE_Type *	base,
		uint64_t	mask
	)

inlinestatic

This function sets the PRINCE mask that is used to mask decrypted data.

Parameters

base	PRINCE peripheral address.
mask	64-bit data mask value.

static void PRINCE_SetLock	(	PRINCE_Type *	base,
		uint32_t	lock
	)

inlinestatic

This function sets lock on specified region registers or mask register.

Parameters

base	PRINCE peripheral address.
lock	registers to lock. This is a logical OR of members of the enumeration prince_lock_t

status_t PRINCE_GenNewIV	(	prince_region_t	region,
		uint8_t *	iv_code,
		bool	store,
		flash_config_t *	flash_context
	)

This function generates new IV code and stores it into the persistent memory. Ensure about 800 bytes free space on the stack when calling this routine with the store parameter set to true!

Parameters

region	PRINCE region index.
iv_code	IV code pointer used for storing the newly generated 52 bytes long IV code.
store	flag to allow storing the newly generated IV code into the persistent memory (FFR).
flash_context	pointer to the flash driver context structure.

Returns: kStatus_Success upon success; kStatus_Fail otherwise, kStatus_Fail is also returned if the key code for the particular PRINCE region is not present in the keystore (though new IV code has been provided)

status_t PRINCE_LoadIV	(	prince_region_t	region,
		uint8_t *	iv_code
	)

This function enables IV code loading into the PRINCE bus encryption engine.

Parameters

region	PRINCE region index.
iv_code	IV code pointer used for passing the IV code.

Returns: kStatus_Success upon success; kStatus_Fail otherwise

status_t PRINCE_SetEncryptForAddressRange	(	prince_region_t	region,
		uint32_t	start_address,
		uint32_t	length,
		flash_config_t *	flash_context,
		bool	regenerate_iv
	)

This function sets the encryption/decryption for specified address range. The SR mask value for the selected Prince region is calculated from provided start_address and length parameters. This calculated value is OR'ed with the actual SR mask value and stored into the PRINCE SR_ENABLE register and also into the persistent memory (FFR) to be used after the device reset. It is possible to define several nonadjacent encrypted areas within one Prince region when calling this function repeatedly. If the length parameter is set to 0, the SR mask value is set to 0 and thus the encryption/decryption for the whole selected Prince region is disabled. Ensure about 800 bytes free space on the stack when calling this routine!

Parameters

region	PRINCE region index.
start_address	start address of the area to be encrypted/decrypted.
length	length of the area to be encrypted/decrypted.
flash_context	pointer to the flash driver context structure.
regenerate_iv	flag to allow IV code regenerating, storing into the persistent memory (FFR) and loading into the PRINCE engine

Returns: kStatus_Success upon success; kStatus_Fail otherwise

status_t PRINCE_GetRegionSREnable	(	PRINCE_Type *	base,
		prince_region_t	region,
		uint32_t *	sr_enable
	)

This function gets PRINCE SR_ENABLE register.

Parameters

base	PRINCE peripheral address.
region	PRINCE region index.
sr_enable	Sub-Region Enable register pointer.

Returns: kStatus_Success upon success; kStatus_InvalidArgument

status_t PRINCE_GetRegionBaseAddress	(	PRINCE_Type *	base,
		prince_region_t	region,
		uint32_t *	region_base_addr
	)

This function gets PRINCE BASE_ADDR register.

Parameters

base	PRINCE peripheral address.
region	PRINCE region index.
region_base_addr	Region base address pointer.

Returns: kStatus_Success upon success; kStatus_InvalidArgument

status_t PRINCE_SetRegionIV	(	PRINCE_Type *	base,
		prince_region_t	region,
		const uint8_t	iv[8]
	)

This function sets specified AES IV for the given region.

Parameters

base	PRINCE peripheral address.
region	Selection of the PRINCE region to be configured.
iv	64-bit AES IV in little-endian byte order.

status_t PRINCE_SetRegionBaseAddress	(	PRINCE_Type *	base,
		prince_region_t	region,
		uint32_t	region_base_addr
	)

This function configures PRINCE region base address.

Parameters

base	PRINCE peripheral address.
region	Selection of the PRINCE region to be configured.
region_base_addr	Base Address for region.

status_t PRINCE_SetRegionSREnable	(	PRINCE_Type *	base,
		prince_region_t	region,
		uint32_t	sr_enable
	)

This function configures PRINCE SR_ENABLE register.

Parameters

base	PRINCE peripheral address.
region	Selection of the PRINCE region to be configured.
sr_enable	Sub-Region Enable register value.

status_t PRINCE_FlashEraseWithChecker	(	flash_config_t *	config,
		uint32_t	start,
		uint32_t	lengthInBytes,
		uint32_t	key
	)

This function erases the appropriate number of flash sectors based on the desired start address and length. It deals with the flash erase function complenentary to the standard erase API of the IAP1 driver. This implementation additionally checks if the whole encrypted PRINCE subregions are erased at once to avoid secrets revealing. The checker implementation is limited to one contiguous PRINCE-controlled memory area.

Parameters

config	The pointer to the flash driver context structure.
start	The start address of the desired flash memory to be erased. The start address needs to be prince-sburegion-aligned.
lengthInBytes	The length, given in bytes (not words or long-words) to be erased. Must be prince-sburegion-size-aligned.
key	The value used to validate all flash erase APIs.

Returns: kStatus_FLASH_Success API was executed successfully.; kStatus_FLASH_InvalidArgument An invalid argument is provided.; kStatus_FLASH_AlignmentError The parameter is not aligned with the specified baseline.; kStatus_FLASH_AddressError The address is out of range.; kStatus_FLASH_EraseKeyError The API erase key is invalid.; kStatus_FLASH_CommandFailure Run-time error during the command execution.; kStatus_FLASH_CommandNotSupported Flash API is not supported.; kStatus_FLASH_EccError A correctable or uncorrectable error during command execution.; kStatus_FLASH_EncryptedRegionsEraseNotDoneAtOnce Encrypted flash subregions are not erased at once.

status_t PRINCE_FlashProgramWithChecker	(	flash_config_t *	config,
		uint32_t	start,
		uint8_t *	src,
		uint32_t	lengthInBytes
	)

This function programs the flash memory with the desired data for a given flash area as determined by the start address and the length. It deals with the flash program function complenentary to the standard program API of the IAP1 driver. This implementation additionally checks if the whole PRINCE subregions are programmed at once to avoid secrets revealing. The checker implementation is limited to one contiguous PRINCE-controlled memory area.

Parameters

config	The pointer to the flash driver context structure.
start	The start address of the desired flash memory to be programmed. Must be prince-sburegion-aligned.
src	A pointer to the source buffer of data that is to be programmed into the flash.
lengthInBytes	The length, given in bytes (not words or long-words), to be programmed. Must be prince-sburegion-size-aligned.

Returns: kStatus_FLASH_Success API was executed successfully.; kStatus_FLASH_InvalidArgument An invalid argument is provided.; kStatus_FLASH_AlignmentError Parameter is not aligned with the specified baseline.; kStatus_FLASH_AddressError Address is out of range.; kStatus_FLASH_AccessError Invalid instruction codes and out-of bounds addresses.; kStatus_FLASH_CommandFailure Run-time error during the command execution.; kStatus_FLASH_CommandFailure Run-time error during the command execution.; kStatus_FLASH_CommandNotSupported Flash API is not supported.; kStatus_FLASH_EccError A correctable or uncorrectable error during command execution.; kStatus_FLASH_SizeError Encrypted flash subregions are not programmed at once.

Overview

Typedefs

Enumerations

Functions

Driver version

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation