MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
BEE: Bus Encryption Engine

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:

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

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

Enumerator
kBEE_AesEcbMode 

AES ECB Mode.

kBEE_AesCtrMode 

AES CTR Mode.

Enumerator
kBEE_Region0 

BEE region 0.

kBEE_Region1 

BEE region 1.

Enumerator
kBEE_AccessProtDisabled 

BEE access permission control disabled.

kBEE_AccessProtEnabled 

BEE access permission control enabled.

Enumerator
kBEE_EndianSwapDisabled 

BEE endian swap disabled.

kBEE_EndianSwapEnabled 

BEE endian swap enabled.

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.

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
baseBEE 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
baseBEE peripheral address.
static void BEE_Enable ( BEE_Type *  base)
inlinestatic

This function enables decryption using BEE.

Parameters
baseBEE peripheral address.
static void BEE_Disable ( BEE_Type *  base)
inlinestatic

This function disables decryption using BEE.

Parameters
baseBEE 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
configConfiguration 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
baseBEE peripheral address.
configConfiguration 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
baseBEE peripheral address.
regionSelection of the BEE region to be configured.
keyAES key (in little-endian format).
keySizeSize 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
baseBEE peripheral address.
regionSelection of the BEE region to be configured.
nonceAES nonce (in little-endian format).
nonceSizeSize of AES nonce.
uint32_t BEE_GetStatusFlags ( BEE_Type *  base)

This function returns status of BEE peripheral.

Parameters
baseBEE 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
baseBEE peripheral base address.
maskThe status flags to clear. This is a logical OR of members of the enumeration bee_status_flags_t