PRINCE: PRINCE bus crypto engine

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

Enumerations
enum	prince_region_t {   kPRINCE_Region0 = 0U,   kPRINCE_Region1 = 1U,   kPRINCE_Region2 = 2U }
enum	prince_lock_t {   kPRINCE_Region0Lock = 1U,   kPRINCE_Region1Lock = 2U,   kPRINCE_Region2Lock = 4U,   kPRINCE_MaskLock = 256U }

Functions
static void	PRINCE_EncryptEnable (PRINCE_Type *base)
	Enable data encryption. More...
static void	PRINCE_EncryptDisable (PRINCE_Type *base)
	Disable 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)
	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...

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

Macro Definition Documentation

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

Current version: 2.0.0

Change log:

• Version 2.0.0
  • Initial version.

Enumeration Type Documentation

enum prince_region_t

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

enum prince_lock_t

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.

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 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. This function is implemented as a wrapper of the exported ROM bootloader API. 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). param 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. This function is implemented as a wrapper of the exported ROM bootloader API.

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
	)

This function sets the encryption/decryption for specified address range. This function is implemented as a wrapper of the exported ROM bootloader API. 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. param flash_context pointer to the flash driver context structure.

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.