Overview

The MCUXpresso SDK provides a peripheral driver for the Bus Encryption Engine (BEE) module.

The BEE module is implemented as an on-the-fly decryption engine. The main features of the BEE module are:

Standard AXI interconnection
On-the-fly AES-128 decryption, supporting ECB and CTR mode
Aliased memory space support. Address remapping for up to two individual regions
Independent AES Key management for those two individual regions
Bus access pattern optimization with the aid of local store and forward buffer
Non-secured access filtering based on security label of the access
Illegal access check and filtering.

The known hardware limitations of the BEE module are as follows:

Only supports 128 bits data width AXI interconnection
Only supports 16-byte burst access size. For a single transaction, the minimum supported access size is limited to 4 bytes.
Granularity of the address bias is 128 KB per step

BEE Driver Initialization and Configuration

The function BEE_Init() initializes the BEE to default values. The function BEE_GetDefaultConfig() loads default values to the BEE configuration structure. The default values are described below.

See the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/bee. The function BEE_Deinit() performs a hardware reset of BEE module and disables clocks. Configuration and keys from software for both regions are cleared.

Enable & Disable BEE

The function BEE_Enable() enables decryption using BEE. The function BEE_Disable() disables decryption using BEE.

Set BEE region config and key

The function BEE_SetConfig() sets BEE settings according to given configuration structure. The structure is described below.

See the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/bee. The function BEE_SetRegionKey() loads given AES key to BEE register for the given region. The key must be 32-bit aligned and stored in little-endian format. Note that eFuse BEE_KEYx_SEL must be set accordingly to be able to load and use the key loaded in BEE registers. Otherwise, the key cannot be loaded and BEE uses the key from OTPMK or SW_GP2.

The function BEE_SetRegionNonce() loads given AES nonce (used only for AES CTR mode) to BEE register for the given region. The nonce must be 32-bit aligned and stored in little-endian format.

Status

Provides functions to get and clear the BEE status.

The function BEE_GetStatusFlags() returns status of BEE peripheral. The function BEE_ClearStatusFlags() clears the BEE status flags.

BEE example

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

Data Structures
struct	bee_region_config_t
	BEE region configuration structure. More...

Enumerations
enum	bee_aes_mode_t { kBEE_AesEcbMode = 0U, kBEE_AesCtrMode = 1U }

enum	bee_region_t { kBEE_Region0 = 0U, kBEE_Region1 = 1U }

enum	bee_ac_prot_enable { kBEE_AccessProtDisabled = 0U, kBEE_AccessProtEnabled = 1U }

enum	bee_endian_swap_enable { kBEE_EndianSwapDisabled = 1U, kBEE_EndianSwapEnabled = 0U }

enum	bee_security_level { kBEE_SecurityLevel0 = 0U, kBEE_SecurityLevel1 = 1U, kBEE_SecurityLevel2 = 2U, kBEE_SecurityLevel3 = 3U }

enum	bee_status_flags_t { kBEE_DisableAbortFlag = 1U, kBEE_Reg0ReadSecViolation = 2U, kBEE_ReadIllegalAccess = 4U, kBEE_Reg1ReadSecViolation = 8U, kBEE_Reg0AccessViolation = 16U, kBEE_Reg1AccessViolation = 32U, kBEE_IdleFlag = BEE_STATUS_BEE_IDLE_MASK }

Functions
void	BEE_Init (BEE_Type *base)
	Resets BEE module to factory default values. More...

void	BEE_Deinit (BEE_Type *base)
	Resets BEE module, clears keys for both regions and disables clock to the BEE. More...

static void	BEE_Enable (BEE_Type *base)
	Enables BEE decryption. More...

static void	BEE_Disable (BEE_Type *base)
	Disables BEE decryption. More...

void	BEE_GetDefaultConfig (bee_region_config_t *config)
	Loads default values to the BEE region configuration structure. More...

void	BEE_SetConfig (BEE_Type base, const bee_region_config_t config)
	Sets BEE configuration. More...

status_t	BEE_SetRegionKey (BEE_Type base, bee_region_t region, const uint8_t key, size_t keySize)
	Loads the AES key for selected region into BEE key registers. More...

status_t	BEE_SetRegionNonce (BEE_Type base, bee_region_t region, const uint8_t nonce, size_t nonceSize)
	Loads the nonce for selected region into BEE nonce registers. More...

uint32_t	BEE_GetStatusFlags (BEE_Type *base)
	Gets the BEE status flags. More...

void	BEE_ClearStatusFlags (BEE_Type *base, uint32_t mask)
	Clears the BEE status flags. More...

Variables
bee_aes_mode_t	bee_region_config_t::region0Mode
	AES mode used for encryption/decryption for region 0.

bee_aes_mode_t	bee_region_config_t::region1Mode
	AES mode used for encryption/decryption for region 1.

uint32_t	bee_region_config_t::region0AddrOffset
	Region 0 address offset.

uint32_t	bee_region_config_t::region1AddrOffset
	Region 1 address offset.

bee_security_level	bee_region_config_t::region0SecLevel
	Region 0 security level.

bee_security_level	bee_region_config_t::region1SecLevel
	Region 1 security level.

uint32_t	bee_region_config_t::region1Bot
	Region 1 bottom address.

uint32_t	bee_region_config_t::region1Top
	Region 1 top address.

bee_ac_prot_enable	bee_region_config_t::accessPermission
	Access permission control enable/disable.

bee_endian_swap_enable	bee_region_config_t::endianSwapEn
	Endian swap enable/disable.

Driver version
#define	FSL_BEE_DRIVER_VERSION (MAKE_VERSION(2, 0, 2))
	BEE driver version. More...

Data Structure Documentation

struct bee_region_config_t

Data Fields
bee_aes_mode_t	region0Mode
	AES mode used for encryption/decryption for region 0.

bee_aes_mode_t	region1Mode
	AES mode used for encryption/decryption for region 1.

uint32_t	region0AddrOffset
	Region 0 address offset.

uint32_t	region1AddrOffset
	Region 1 address offset.

bee_security_level	region0SecLevel
	Region 0 security level.

bee_security_level	region1SecLevel
	Region 1 security level.

uint32_t	region1Bot
	Region 1 bottom address.

uint32_t	region1Top
	Region 1 top address.

bee_ac_prot_enable	accessPermission
	Access permission control enable/disable.

bee_endian_swap_enable	endianSwapEn
	Endian swap enable/disable.

Macro Definition Documentation

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

Version 2.0.2.

Current version: 2.0.2

Change log:

Version 2.0.2
- Fix MISRA issue
2.0.1
- Bug Fixes
  - Fixed bug in key user key loading sequence. BEE must be enabled during loading of user key.
  - Fixed typos in comments.
- New Features
  - Added configuration setting for endian swap, access permission and region security level.
- Improvements
  - Setting of AES nonce was moved from BEE_SetRegionKey() into separate BEE_SetRegionNonce() function.
    - Changed handling of region settings. Both regions are configured simultaneously by BEE_SetConfig() function. Configuration of FAC start and end address using IOMUXC_GPRs was moved to application.
  - Default value for region address offset was changed to 0.
Version 2.0.0
- Initial version

Enumeration Type Documentation

enum bee_aes_mode_t

Enumerator
kBEE_AesEcbMode	AES ECB Mode.
kBEE_AesCtrMode	AES CTR Mode.

enum bee_region_t

Enumerator
kBEE_Region0	BEE region 0.
kBEE_Region1	BEE region 1.

enum bee_ac_prot_enable

Enumerator
kBEE_AccessProtDisabled	BEE access permission control disabled.
kBEE_AccessProtEnabled	BEE access permission control enabled.

enum bee_endian_swap_enable

Enumerator
kBEE_EndianSwapDisabled	BEE endian swap disabled.
kBEE_EndianSwapEnabled	BEE endian swap enabled.

enum bee_security_level

Enumerator
kBEE_SecurityLevel0	BEE security level 0.
kBEE_SecurityLevel1	BEE security level 1.
kBEE_SecurityLevel2	BEE security level 2.
kBEE_SecurityLevel3	BEE security level 3.

enum bee_status_flags_t

Enumerator
kBEE_DisableAbortFlag	Disable abort flag.
kBEE_Reg0ReadSecViolation	Region-0 read channel security violation.
kBEE_ReadIllegalAccess	Read channel illegal access detected.
kBEE_Reg1ReadSecViolation	Region-1 read channel security violation.
kBEE_Reg0AccessViolation	Protected region-0 access violation.
kBEE_Reg1AccessViolation	Protected region-1 access violation.
kBEE_IdleFlag	Idle flag.

Function Documentation

void BEE_Init ( BEE_Type * base )

This function performs hardware reset of BEE module. Attributes and keys from software for both regions are cleared.

Parameters

base	BEE peripheral address.

void BEE_Deinit ( BEE_Type * base )

This function performs hardware reset of BEE module and disables clocks. Attributes and keys from software for both regions are cleared.

Parameters

base	BEE peripheral address.

static void BEE_Enable ( BEE_Type * base )

inlinestatic

This function enables decryption using BEE.

Parameters

base	BEE peripheral address.

static void BEE_Disable ( BEE_Type * base )

inlinestatic

This function disables decryption using BEE.

Parameters

base	BEE peripheral address.

void BEE_GetDefaultConfig ( bee_region_config_t * config )

Loads default values to the BEE region configuration structure. The default values are as follows:

*   config->region0Mode = kBEE_AesCtrMode;
*   config->region1Mode = kBEE_AesCtrMode;
*   config->region0AddrOffset = 0U;
*   config->region1AddrOffset = 0U;
*   config->region0SecLevel = kBEE_SecurityLevel3;
*   config->region1SecLevel = kBEE_SecurityLevel3;
*   config->region1Bot = 0U;
*   config->region1Top = 0U;
*   config->accessPermission = kBEE_AccessProtDisabled;
*   config->endianSwapEn = kBEE_EndianSwapEnabled;
* 

Parameters

config Configuration structure for BEE peripheral.

void BEE_SetConfig	(	BEE_Type *	base,
		const bee_region_config_t *	config
	)

This function sets BEE peripheral and BEE region settings accorging to given configuration structure.

Parameters

base	BEE peripheral address.
config	Configuration structure for BEE.

status_t BEE_SetRegionKey	(	BEE_Type *	base,
		bee_region_t	region,
		const uint8_t *	key,
		size_t	keySize
	)

This function loads given AES key to BEE register for the given region. The key must be 32-bit aligned and stored in little-endian format.

Please note, that eFuse BEE_KEYx_SEL must be set accordingly to be able to load and use key loaded in BEE registers. Otherwise, key cannot loaded and BEE will use key from OTPMK or SW_GP2.

Parameters

base	BEE peripheral address.
region	Selection of the BEE region to be configured.
key	AES key (in little-endian format).
keySize	Size of AES key.

status_t BEE_SetRegionNonce	(	BEE_Type *	base,
		bee_region_t	region,
		const uint8_t *	nonce,
		size_t	nonceSize
	)

This function loads given nonce(only AES CTR mode) to BEE register for the given region. The nonce must be 32-bit aligned and stored in little-endian format.

Parameters

base	BEE peripheral address.
region	Selection of the BEE region to be configured.
nonce	AES nonce (in little-endian format).
nonceSize	Size of AES nonce.

uint32_t BEE_GetStatusFlags ( BEE_Type * base )

This function returns status of BEE peripheral.

Parameters

base	BEE peripheral address.

Returns: The status flags. This is the logical OR of members of the enumeration bee_status_flags_t

void BEE_ClearStatusFlags	(	BEE_Type *	base,
		uint32_t	mask
	)

Parameters

base	BEE peripheral base address.
mask	The status flags to clear. This is a logical OR of members of the enumeration bee_status_flags_t

Overview

BEE Driver Initialization and Configuration

Enable & Disable BEE

Set BEE region config and key

Status

BEE example

Data Structures

Enumerations

Functions

Variables

Driver version

Data Structure Documentation

Data Fields

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation