Detailed Description

Cryptographic Services Engine Peripheral Driver.

How to use the CSEc driver in your application

To access the command feature set, the part must be configured for EEE operation, using the PGMPART command. This can be implemented by using the Flash driver. By enabling security features and configuring a number of user keys, the total size of the 4 KByte EEERAM will be reduced by the space required to store the user keys. The user key space will then effectively be unaddressable space in the EEERAM.

At the bottom of this page is an example of making this configuration using the Flash driver. For more details related to the FLASH_DRV_DEFlashPartition function, please refer to the Flash driver documentation. Please note that this configuration is required only once and should not be lanched from Flash memory.

In order to use the CSEc driver in your application, the CSEC_DRV_Init function should be called prior to using the rest of the API. The parameter of this function is used for holding the internal state of the driver throughout the lifetime of the application.

Key/seed/random number generation

This is the high level flow in which to initialize and generate random numbers.

  1. Run CSEC_DRV_InitRNG to initialize a random seed from the internal TRNG
    • CSEC_DRV_InitRNG must be run after every POR, and before the first execution of CSEC_DRV_GenerateRND
    • Note that if the next step (run CSEC_DRV_GenerateRND) is run without initializing the seed, CSEC_RNG_SEED will be returned.
  2. Run CSEC_DRV_GenerateRND to generate a random numer The PRNG uses the PRNG_STATE/KEY and Seed per SHE spec and the AIS20 standard.
  3. For additional random numbers the user may continue executing CSEC_DRV_GenerateRND unless a POR event occurred.

Memory update protocol

In order to update a key, the user must have knowledge of a valid authentication secret, i.e. another key (AuthID). If the key AuthID is empty, the key update will only work if AuthID = ID (the key that will be updated will represent the AuthID from now on), otherwise CSEC_KEY_EMPTY is returned.

The M1-M3 values need to be computed according to the SHE Specification in order to update a key slot. The CSEC_DRV_LoadKey function will require those values. After successfully updating the key slot, two verification values will be returned: M4 and M5. The user can compute the two values and compare them with the ones returned by the CSEC_DRV_LoadKey function in order to ensure the slot was updated as desired. Please refer to the CSEc driver example for a reference implementation of the memory update protocol.

Examples:

Using the Flash driver to partition Flash for CSEc operation

flash_ssd_config_t flashSSDConfig;
FLASH_DRV_Init(&flash1_InitConfig0, &flashSSDConfig);
/* Configure the part for EEE operation, with 20 keys for CSEc */
FLASH_DRV_DEFlashPartition(&flashSSDConfig, 0x2, 0x4, 0x3, false);

Encryption using AES EBC mode

uint8_t plainText[16] = {0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF};
uint8_t plainKey[16] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
csec_error_code_t stat;
uint8_t cipherText[16];
csec_state_t csecState;
CSEC_DRV_Init(&csecState);
stat = CSEC_DRV_LoadPlainKey(plainKey);
if (stat != CSEC_NO_ERROR)
{
/* Loading the key failed, encryption will not have the expected result */
return false;
}
stat = CSEC_DRV_EncryptECB(CSEC_RAM_KEY, plainText, 16U, cipherText, 1U);
if (stat != CSEC_NO_ERROR)
{
/* Encryption was successful */
return true;
}

Generating and verifying CMAC for a message

uint8_t plainKey[16] = {0x2b, 0x7e, 0x15, 0x16, 0x28, 0xae, 0xd2, 0xa6, 0xab,
0xf7, 0x15, 0x88, 0x09, 0xcf, 0x4f, 0x3c};
uint8_t msg[16] = {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08,
0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f};
uint8_t cmac[16];
bool verifStatus;
csec_error_code_t stat;
csec_state_t csecState;
CSEC_DRV_Init(&csecState);
stat = CSEC_DRV_LoadPlainKey(plainKey);
if (stat != CSEC_NO_ERROR)
return false;
stat = CSEC_DRV_GenerateMAC(CSEC_RAM_KEY, msg, 128U, cmac, 1U);
if (stat != CSEC_NO_ERROR)
return false;
stat = CSEC_DRV_VerifyMAC(CSEC_RAM_KEY, msg, 128U, cmac, 128U, &verifStatus, 1U);
if (stat != CSEC_NO_ERROR)
return false;
if (!verifStatus)
{
/* The given CMAC did not matched with the one computed internally */
return false;
}

Generating random bits

csec_error_code_t stat;
uint8_t rnd[16];
csec_state_t csecState;
CSEC_DRV_Init(&csecState);
if (stat != CSEC_NO_ERROR)
return false;
/* Check RNG is initialized */
status = CSEC_DRV_GetStatus();
if (!(status & CSEC_STATUS_RND_INIT))
return false;
if (stat != CSEC_NO_ERROR)
return false;

Data Structures

struct  csec_state_t
 Internal driver state information. More...
 

Macros

#define CSEC_STATUS_BUSY   (0x1U)
 The bit is set whenever SHE is processing a command. More...
 
#define CSEC_STATUS_SECURE_BOOT   (0x2U)
 The bit is set if the secure booting is activated. More...
 
#define CSEC_STATUS_BOOT_INIT   (0x4U)
 The bit is set if the secure booting has been personalized during the boot sequence. More...
 
#define CSEC_STATUS_BOOT_FINISHED   (0x8U)
 The bit is set when the secure booting has been finished by calling either CMD_BOOT_FAILURE or CMD_BOOT_OK or if CMD_SECURE_BOOT failed in verifying BOOT_MAC. More...
 
#define CSEC_STATUS_BOOT_OK   (0x10U)
 The bit is set if the secure booting (CMD_SECURE_BOOT) succeeded. If CMD_BOOT_FAILURE is called the bit is erased. More...
 
#define CSEC_STATUS_RND_INIT   (0x20U)
 The bit is set if the random number generator has been initialized. More...
 
#define CSEC_STATUS_EXT_DEBUGGER   (0x40U)
 The bit is set if an external debugger is connected to the chip. More...
 
#define CSEC_STATUS_INT_DEBUGGER   (0x80U)
 The bit is set if the internal debugging mechanisms of SHE are activated. More...
 

Typedefs

typedef uint8_t csec_status_t
 Represents the status of the CSEc module. Provides one bit for each status code as per SHE specification. CSEC_STATUS_* masks can be used for verifying the status. More...
 

Enumerations

enum  csec_key_id_t {
  CSEC_SECRET_KEY = 0x0U, CSEC_MASTER_ECU, CSEC_BOOT_MAC_KEY, CSEC_BOOT_MAC,
  CSEC_KEY_1, CSEC_KEY_2, CSEC_KEY_3, CSEC_KEY_4,
  CSEC_KEY_5, CSEC_KEY_6, CSEC_KEY_7, CSEC_KEY_8,
  CSEC_KEY_9, CSEC_KEY_10, CSEC_RAM_KEY = 0xFU, CSEC_KEY_11 = 0x14U,
  CSEC_KEY_12, CSEC_KEY_13, CSEC_KEY_14, CSEC_KEY_15,
  CSEC_KEY_16, CSEC_KEY_17
}
 Specify the KeyID to be used to implement the requested cryptographic operation. More...
 
enum  csec_cmd_t {
  CSEC_CMD_ENC_ECB = 0x1U, CSEC_CMD_ENC_CBC, CSEC_CMD_DEC_ECB, CSEC_CMD_DEC_CBC,
  CSEC_CMD_GENERATE_MAC, CSEC_CMD_VERIFY_MAC, CSEC_CMD_LOAD_KEY, CSEC_CMD_LOAD_PLAIN_KEY,
  CSEC_CMD_EXPORT_RAM_KEY, CSEC_CMD_INIT_RNG, CSEC_CMD_EXTEND_SEED, CSEC_CMD_RND,
  CSEC_CMD_RESERVED_1, CSEC_CMD_BOOT_FAILURE, CSEC_CMD_BOOT_OK, CSEC_CMD_GET_ID,
  CSEC_CMD_BOOT_DEFINE, CSEC_CMD_DBG_CHAL, CSEC_CMD_DBG_AUTH, CSEC_CMD_RESERVED_2,
  CSEC_CMD_RESERVED_3, CSEC_CMD_MP_COMPRESS
}
 CSEc commands which follow the same values as the SHE command definition. More...
 
enum  csec_call_sequence_t { CSEC_CALL_SEQ_FIRST, CSEC_CALL_SEQ_SUBSEQUENT }
 Specifies if the information is the first or a following function call. More...
 
enum  csec_boot_flavor_t { CSEC_BOOT_STRICT, CSEC_BOOT_SERIAL, CSEC_BOOT_PARALLEL, CSEC_BOOT_NOT_DEFINED }
 Specifies the boot type for the BOOT_DEFINE command. More...
 

Functions

void CSEC_DRV_Init (csec_state_t *state)
 Initializes the internal state of the driver and enables the FTFC interrupt. More...
 
void CSEC_DRV_Deinit (void)
 Clears the internal state of the driver and disables the FTFC interrupt. More...
 
status_t CSEC_DRV_EncryptECB (csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, uint8_t *cipherText, uint32_t timeout)
 Performs the AES-128 encryption in ECB mode. More...
 
status_t CSEC_DRV_DecryptECB (csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, uint8_t *plainText, uint32_t timeout)
 Performs the AES-128 decryption in ECB mode. More...
 
status_t CSEC_DRV_EncryptCBC (csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, const uint8_t *iv, uint8_t *cipherText, uint32_t timeout)
 Performs the AES-128 encryption in CBC mode. More...
 
status_t CSEC_DRV_DecryptCBC (csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, const uint8_t *iv, uint8_t *plainText, uint32_t timeout)
 Performs the AES-128 decryption in CBC mode. More...
 
status_t CSEC_DRV_GenerateMAC (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac, uint32_t timeout)
 Calculates the MAC of a given message using CMAC with AES-128. More...
 
status_t CSEC_DRV_GenerateMACAddrMode (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac)
 Calculates the MAC of a given message (located in Flash) using CMAC with AES-128. More...
 
status_t CSEC_DRV_VerifyMAC (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus, uint32_t timeout)
 Verifies the MAC of a given message using CMAC with AES-128. More...
 
status_t CSEC_DRV_VerifyMACAddrMode (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
 Verifies the MAC of a given message (located in Flash) using CMAC with AES-128. More...
 
status_t CSEC_DRV_LoadKey (csec_key_id_t keyId, const uint8_t *m1, const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5)
 Updates an internal key per the SHE specification. More...
 
status_t CSEC_DRV_LoadPlainKey (const uint8_t *plainKey)
 Updates the RAM key memory slot with a 128-bit plaintext. More...
 
status_t CSEC_DRV_ExportRAMKey (uint8_t *m1, uint8_t *m2, uint8_t *m3, uint8_t *m4, uint8_t *m5)
 Exports the RAM_KEY into a format protected by SECRET_KEY. More...
 
status_t CSEC_DRV_InitRNG (void)
 Initializes the seed and derives a key for the PRNG. More...
 
status_t CSEC_DRV_ExtendSeed (const uint8_t *entropy)
 Extends the seed of the PRNG. More...
 
status_t CSEC_DRV_GenerateRND (uint8_t *rnd)
 Generates a vector of 128 random bits. More...
 
status_t CSEC_DRV_BootFailure (void)
 Signals a failure detected during later stages of the boot process. More...
 
status_t CSEC_DRV_BootOK (void)
 Marks a successful boot verification during later stages of the boot process. More...
 
status_t CSEC_DRV_BootDefine (uint32_t bootSize, csec_boot_flavor_t bootFlavor)
 Implements an extension of the SHE standard to define both the user boot size and boot method. More...
 
static csec_status_t CSEC_DRV_GetStatus (void)
 Returns the content of the status register. More...
 
status_t CSEC_DRV_GetID (const uint8_t *challenge, uint8_t *uid, uint8_t *sreg, uint8_t *mac)
 Returns the identity (UID) and the value of the status register protected by a MAC over a challenge and the data. More...
 
status_t CSEC_DRV_DbgChal (uint8_t *challenge)
 Obtains a random number which the user shall use along with the MASTER_ECU_KEY and UID to return an authorization request. More...
 
status_t CSEC_DRV_DbgAuth (const uint8_t *authorization)
 Erases all keys (actual and outdated) stored in NVM Memory if the authorization is confirmed by CSEc. More...
 
status_t CSEC_DRV_MPCompress (const uint8_t *msg, uint16_t msgLen, uint8_t *mpCompress, uint32_t timeout)
 Compresses the given messages by accessing the Miyaguchi-Prenell compression feature with in the CSEc feature set. More...
 
status_t CSEC_DRV_EncryptECBAsync (csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, uint8_t *cipherText)
 Asynchronously performs the AES-128 encryption in ECB mode. More...
 
status_t CSEC_DRV_DecryptECBAsync (csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, uint8_t *plainText)
 Asynchronously performs the AES-128 decryption in ECB mode. More...
 
status_t CSEC_DRV_EncryptCBCAsync (csec_key_id_t keyId, const uint8_t *plainText, uint32_t length, const uint8_t *iv, uint8_t *cipherText)
 Asynchronously performs the AES-128 encryption in CBC mode. More...
 
status_t CSEC_DRV_DecryptCBCAsync (csec_key_id_t keyId, const uint8_t *cipherText, uint32_t length, const uint8_t *iv, uint8_t *plainText)
 Asynchronously performs the AES-128 decryption in CBC mode. More...
 
status_t CSEC_DRV_GenerateMACAsync (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, uint8_t *cmac)
 Asynchronously calculates the MAC of a given message using CMAC with AES-128. More...
 
status_t CSEC_DRV_VerifyMACAsync (csec_key_id_t keyId, const uint8_t *msg, uint32_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
 Asynchronously verifies the MAC of a given message using CMAC with AES-128. More...
 
status_t CSEC_DRV_GetAsyncCmdStatus (void)
 Checks the status of the execution of an asynchronous command. More...
 
void CSEC_DRV_InstallCallback (security_callback_t callbackFunc, void *callbackParam)
 Installs a callback function which will be invoked when an asynchronous command finishes its execution. More...
 
void CSEC_DRV_CancelCommand (void)
 Cancels a previously launched asynchronous command. More...
 

Macro Definition Documentation

#define CSEC_STATUS_BOOT_FINISHED   (0x8U)

The bit is set when the secure booting has been finished by calling either CMD_BOOT_FAILURE or CMD_BOOT_OK or if CMD_SECURE_BOOT failed in verifying BOOT_MAC.

Definition at line 73 of file csec_driver.h.

#define CSEC_STATUS_BOOT_INIT   (0x4U)

The bit is set if the secure booting has been personalized during the boot sequence.

Definition at line 69 of file csec_driver.h.

#define CSEC_STATUS_BOOT_OK   (0x10U)

The bit is set if the secure booting (CMD_SECURE_BOOT) succeeded. If CMD_BOOT_FAILURE is called the bit is erased.

Definition at line 76 of file csec_driver.h.

#define CSEC_STATUS_BUSY   (0x1U)

The bit is set whenever SHE is processing a command.

Definition at line 64 of file csec_driver.h.

#define CSEC_STATUS_EXT_DEBUGGER   (0x40U)

The bit is set if an external debugger is connected to the chip.

Definition at line 80 of file csec_driver.h.

#define CSEC_STATUS_INT_DEBUGGER   (0x80U)

The bit is set if the internal debugging mechanisms of SHE are activated.

Definition at line 83 of file csec_driver.h.

#define CSEC_STATUS_RND_INIT   (0x20U)

The bit is set if the random number generator has been initialized.

Definition at line 78 of file csec_driver.h.

#define CSEC_STATUS_SECURE_BOOT   (0x2U)

The bit is set if the secure booting is activated.

Definition at line 66 of file csec_driver.h.

Typedef Documentation

typedef uint8_t csec_status_t

Represents the status of the CSEc module. Provides one bit for each status code as per SHE specification. CSEC_STATUS_* masks can be used for verifying the status.

Implements : csec_status_t_Class

Definition at line 92 of file csec_driver.h.

Enumeration Type Documentation

Specifies the boot type for the BOOT_DEFINE command.

Implements : csec_boot_flavor_t_Class

Enumerator
CSEC_BOOT_STRICT 
CSEC_BOOT_SERIAL 
CSEC_BOOT_PARALLEL 
CSEC_BOOT_NOT_DEFINED 

Definition at line 170 of file csec_driver.h.

Specifies if the information is the first or a following function call.

Implements : csec_call_sequence_t_Class

Enumerator
CSEC_CALL_SEQ_FIRST 
CSEC_CALL_SEQ_SUBSEQUENT 

Definition at line 160 of file csec_driver.h.

enum csec_cmd_t

CSEc commands which follow the same values as the SHE command definition.

Implements : csec_cmd_t_Class

Enumerator
CSEC_CMD_ENC_ECB 
CSEC_CMD_ENC_CBC 
CSEC_CMD_DEC_ECB 
CSEC_CMD_DEC_CBC 
CSEC_CMD_GENERATE_MAC 
CSEC_CMD_VERIFY_MAC 
CSEC_CMD_LOAD_KEY 
CSEC_CMD_LOAD_PLAIN_KEY 
CSEC_CMD_EXPORT_RAM_KEY 
CSEC_CMD_INIT_RNG 
CSEC_CMD_EXTEND_SEED 
CSEC_CMD_RND 
CSEC_CMD_RESERVED_1 
CSEC_CMD_BOOT_FAILURE 
CSEC_CMD_BOOT_OK 
CSEC_CMD_GET_ID 
CSEC_CMD_BOOT_DEFINE 
CSEC_CMD_DBG_CHAL 
CSEC_CMD_DBG_AUTH 
CSEC_CMD_RESERVED_2 
CSEC_CMD_RESERVED_3 
CSEC_CMD_MP_COMPRESS 

Definition at line 130 of file csec_driver.h.

Specify the KeyID to be used to implement the requested cryptographic operation.

Implements : csec_key_id_t_Class

Enumerator
CSEC_SECRET_KEY 
CSEC_MASTER_ECU 
CSEC_BOOT_MAC_KEY 
CSEC_BOOT_MAC 
CSEC_KEY_1 
CSEC_KEY_2 
CSEC_KEY_3 
CSEC_KEY_4 
CSEC_KEY_5 
CSEC_KEY_6 
CSEC_KEY_7 
CSEC_KEY_8 
CSEC_KEY_9 
CSEC_KEY_10 
CSEC_RAM_KEY 
CSEC_KEY_11 
CSEC_KEY_12 
CSEC_KEY_13 
CSEC_KEY_14 
CSEC_KEY_15 
CSEC_KEY_16 
CSEC_KEY_17 

Definition at line 100 of file csec_driver.h.

Function Documentation

status_t CSEC_DRV_BootDefine ( uint32_t  bootSize,
csec_boot_flavor_t  bootFlavor 
)

Implements an extension of the SHE standard to define both the user boot size and boot method.

The function implements an extension of the SHE standard to define both the user boot size and boot method.

Parameters
[in]bootSizeNumber of blocks of 128-bit data to check on boot. Maximum size is 512kBytes.
[in]bootFlavorThe boot method.
Returns
Error Code after command execution.

Definition at line 929 of file csec_driver.c.

status_t CSEC_DRV_BootFailure ( void  )

Signals a failure detected during later stages of the boot process.

The function is called during later stages of the boot process to detect a failure.

Returns
Error Code after command execution.

Definition at line 861 of file csec_driver.c.

status_t CSEC_DRV_BootOK ( void  )

Marks a successful boot verification during later stages of the boot process.

The function is called during later stages of the boot process to mark successful boot verification.

Returns
Error Code after command execution.

Definition at line 895 of file csec_driver.c.

void CSEC_DRV_CancelCommand ( void  )

Cancels a previously launched asynchronous command.

Definition at line 1778 of file csec_driver.c.

status_t CSEC_DRV_DbgAuth ( const uint8_t *  authorization)

Erases all keys (actual and outdated) stored in NVM Memory if the authorization is confirmed by CSEc.

This function erases all keys (actual and outdated) stored in NVM Memory if the authorization is confirmed by CSEc.

Parameters
[in]authorizationPointer to the 128-bit buffer containing the authorization value.
Returns
Error Code after command execution.

Definition at line 1060 of file csec_driver.c.

status_t CSEC_DRV_DbgChal ( uint8_t *  challenge)

Obtains a random number which the user shall use along with the MASTER_ECU_KEY and UID to return an authorization request.

This function obtains a random number which the user shall use along with the MASTER_ECU_KEY and UID to return an authorization request.

Parameters
[out]challengePointer to the 128-bit buffer where the challenge data will be stored.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 1020 of file csec_driver.c.

status_t CSEC_DRV_DecryptCBC ( csec_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  length,
const uint8_t *  iv,
uint8_t *  plainText,
uint32_t  timeout 
)

Performs the AES-128 decryption in CBC mode.

This function performs the AES-128 decryption in CBC mode of the input cipher text buffer.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]cipherTextPointer to the cipher text buffer.
[in]lengthNumber of bytes of cipher text message to be decrypted. It should be multiple of 16 bytes.
[in]ivPointer to the initialization vector buffer.
[out]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 330 of file csec_driver.c.

status_t CSEC_DRV_DecryptCBCAsync ( csec_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  length,
const uint8_t *  iv,
uint8_t *  plainText 
)

Asynchronously performs the AES-128 decryption in CBC mode.

This function performs the AES-128 decryption in CBC mode of the input cipher text buffer, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]cipherTextPointer to the cipher text buffer.
[in]lengthNumber of bytes of cipher text message to be decrypted. It should be multiple of 16 bytes.
[in]ivPointer to the initialization vector buffer.
[out]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1280 of file csec_driver.c.

status_t CSEC_DRV_DecryptECB ( csec_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  length,
uint8_t *  plainText,
uint32_t  timeout 
)

Performs the AES-128 decryption in ECB mode.

This function performs the AES-128 decryption in ECB mode of the input cipher text buffer.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation
[in]cipherTextPointer to the cipher text buffer.
[in]lengthNumber of bytes of cipher text message to be decrypted. It should be multiple of 16 bytes.
[out]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 222 of file csec_driver.c.

status_t CSEC_DRV_DecryptECBAsync ( csec_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  length,
uint8_t *  plainText 
)

Asynchronously performs the AES-128 decryption in ECB mode.

This function performs the AES-128 decryption in ECB mode of the input cipher text buffer, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation
[in]cipherTextPointer to the cipher text buffer.
[in]lengthNumber of bytes of cipher text message to be decrypted. It should be multiple of 16 bytes.
[out]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1213 of file csec_driver.c.

void CSEC_DRV_Deinit ( void  )

Clears the internal state of the driver and disables the FTFC interrupt.

Definition at line 154 of file csec_driver.c.

status_t CSEC_DRV_EncryptCBC ( csec_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  length,
const uint8_t *  iv,
uint8_t *  cipherText,
uint32_t  timeout 
)

Performs the AES-128 encryption in CBC mode.

This function performs the AES-128 encryption in CBC mode of the input plaintext buffer.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]lengthNumber of bytes of plain text message to be encrypted. It should be multiple of 16 bytes.
[in]ivPointer to the initialization vector buffer.
[in]timeoutTimeout in milliseconds.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 274 of file csec_driver.c.

status_t CSEC_DRV_EncryptCBCAsync ( csec_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  length,
const uint8_t *  iv,
uint8_t *  cipherText 
)

Asynchronously performs the AES-128 encryption in CBC mode.

This function performs the AES-128 encryption in CBC mode of the input plaintext buffer, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]lengthNumber of bytes of plain text message to be encrypted. It should be multiple of 16 bytes.
[in]ivPointer to the initialization vector buffer.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1245 of file csec_driver.c.

status_t CSEC_DRV_EncryptECB ( csec_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  length,
uint8_t *  cipherText,
uint32_t  timeout 
)

Performs the AES-128 encryption in ECB mode.

This function performs the AES-128 encryption in ECB mode of the input plain text buffer

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]lengthNumber of bytes of plain text message to be encrypted. It should be multiple of 16 bytes.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 169 of file csec_driver.c.

status_t CSEC_DRV_EncryptECBAsync ( csec_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  length,
uint8_t *  cipherText 
)

Asynchronously performs the AES-128 encryption in ECB mode.

This function performs the AES-128 encryption in ECB mode of the input plain text buffer, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]lengthNumber of bytes of plain text message to be encrypted. It should be multiple of 16 bytes.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1181 of file csec_driver.c.

status_t CSEC_DRV_ExportRAMKey ( uint8_t *  m1,
uint8_t *  m2,
uint8_t *  m3,
uint8_t *  m4,
uint8_t *  m5 
)

Exports the RAM_KEY into a format protected by SECRET_KEY.

This function exports the RAM_KEY into a format protected by SECRET_KEY.

Parameters
[out]m1Pointer to a buffer where the M1 parameter will be exported.
[out]m2Pointer to a buffer where the M2 parameter will be exported.
[out]m3Pointer to a buffer where the M3 parameter will be exported.
[out]m4Pointer to a buffer where the M4 parameter will be exported.
[out]m5Pointer to a buffer where the M5 parameter will be exported.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 694 of file csec_driver.c.

status_t CSEC_DRV_ExtendSeed ( const uint8_t *  entropy)

Extends the seed of the PRNG.

Extends the seed of the PRNG by compressing the former seed value and the supplied entropy into a new seed. This new seed is then to be used to generate a random number by invoking the CMD_RND command. The random number generator must be initialized by CMD_INIT_RNG before the seed may be extended.

Parameters
[in]entropyPointer to a 128-bit buffer containing the entropy.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 783 of file csec_driver.c.

status_t CSEC_DRV_GenerateMAC ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
uint8_t *  cmac,
uint32_t  timeout 
)

Calculates the MAC of a given message using CMAC with AES-128.

This function calculates the MAC of a given message using CMAC with AES-128.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer.
[in]msgLenNumber of bits of message on which CMAC will be computed.
[out]cmacPointer to the buffer containing the result of the CMAC computation.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 386 of file csec_driver.c.

status_t CSEC_DRV_GenerateMACAddrMode ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
uint8_t *  cmac 
)

Calculates the MAC of a given message (located in Flash) using CMAC with AES-128.

This function calculates the MAC of a given message using CMAC with AES-128. It is different from the CSEC_DRV_GenerateMAC function in the sense that it does not involve an extra copy of the data on which the CMAC is computed and the message pointer should be a pointer to Flash memory.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer (pointing to Flash memory).
[in]msgLenNumber of bits of message on which CMAC will be computed.
[out]cmacPointer to the buffer containing the result of the CMAC computation.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 442 of file csec_driver.c.

status_t CSEC_DRV_GenerateMACAsync ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
uint8_t *  cmac 
)

Asynchronously calculates the MAC of a given message using CMAC with AES-128.

This function calculates the MAC of a given message using CMAC with AES-128, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer.
[in]msgLenNumber of bits of message on which CMAC will be computed.
[out]cmacPointer to the buffer containing the result of the CMAC computation.
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1315 of file csec_driver.c.

status_t CSEC_DRV_GenerateRND ( uint8_t *  rnd)

Generates a vector of 128 random bits.

The function returns a vector of 128 random bits. The random number generator has to be initialized by calling CSEC_DRV_InitRNG before random numbers can be supplied.

Parameters
[out]rndPointer to a 128-bit buffer where the generated random number has to be stored.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 821 of file csec_driver.c.

status_t CSEC_DRV_GetAsyncCmdStatus ( void  )

Checks the status of the execution of an asynchronous command.

This function checks the status of the execution of an asynchronous command. If the command is still in progress, returns STATUS_BUSY.

Returns
Error Code after command execution.

Definition at line 1388 of file csec_driver.c.

status_t CSEC_DRV_GetID ( const uint8_t *  challenge,
uint8_t *  uid,
uint8_t *  sreg,
uint8_t *  mac 
)

Returns the identity (UID) and the value of the status register protected by a MAC over a challenge and the data.

This function returns the identity (UID) and the value of the status register protected by a MAC over a challenge and the data.

Parameters
[in]challengePointer to the 128-bit buffer containing Challenge data.
[out]uidPointer to 120 bit buffer where the UID will be stored.
[out]sregValue of the status register.
[out]macPointer to the 128 bit buffer where the MAC generated over challenge and UID and status will be stored.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 968 of file csec_driver.c.

static csec_status_t CSEC_DRV_GetStatus ( void  )
inlinestatic

Returns the content of the status register.

The function shall return the content of the status register.

Returns
Value of the status register.

Implements : CSEC_DRV_GetStatus_Activity

Definition at line 529 of file csec_driver.h.

void CSEC_DRV_Init ( csec_state_t state)

Initializes the internal state of the driver and enables the FTFC interrupt.

Parameters
[in]statePointer to the state structure which will be used for holding the internal state of the driver.

Definition at line 134 of file csec_driver.c.

status_t CSEC_DRV_InitRNG ( void  )

Initializes the seed and derives a key for the PRNG.

The function initializes the seed and derives a key for the PRNG. The function must be called before CMD_RND after every power cycle/reset.

Returns
Error Code after command execution.

Definition at line 746 of file csec_driver.c.

void CSEC_DRV_InstallCallback ( security_callback_t  callbackFunc,
void *  callbackParam 
)

Installs a callback function which will be invoked when an asynchronous command finishes its execution.

Parameters
[in]callbackFuncThe function to be invoked.
[in]callbackParamThe parameter to be passed to the callback function.

Definition at line 1763 of file csec_driver.c.

status_t CSEC_DRV_LoadKey ( csec_key_id_t  keyId,
const uint8_t *  m1,
const uint8_t *  m2,
const uint8_t *  m3,
uint8_t *  m4,
uint8_t *  m5 
)

Updates an internal key per the SHE specification.

This function updates an internal key per the SHE specification.

Parameters
[in]keyIdKeyID of the key to be updated.
[in]m1Pointer to the 128-bit M1 message containing the UID, Key ID and Authentication Key ID.
[in]m2Pointer to the 256-bit M2 message contains the new security flags, counter and the key value all encrypted using a derived key generated from the Authentication Key.
[in]m3Pointer to the 128-bit M3 message is a MAC generated over messages M1 and M2.
[out]m4Pointer to a 256 bits buffer where the computed M4 parameter is stored.
[out]m5Pointer to a 128 bits buffer where the computed M5 parameters is stored.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 603 of file csec_driver.c.

status_t CSEC_DRV_LoadPlainKey ( const uint8_t *  plainKey)

Updates the RAM key memory slot with a 128-bit plaintext.

The function updates the RAM key memory slot with a 128-bit plaintext. The key is loaded without encryption and verification of the key, i.e. the key is handed over in plaintext. A plain key can only be loaded into the RAM_KEY slot.

Parameters
[in]plainKeyPointer to the 128-bit buffer containing the key that needs to be copied in RAM_KEY slot.
Returns
Error Code after command execution.

Definition at line 657 of file csec_driver.c.

status_t CSEC_DRV_MPCompress ( const uint8_t *  msg,
uint16_t  msgLen,
uint8_t *  mpCompress,
uint32_t  timeout 
)

Compresses the given messages by accessing the Miyaguchi-Prenell compression feature with in the CSEc feature set.

This function accesses a Miyaguchi-Prenell compression feature within the CSEc feature set to compress the given messages.

Parameters
[in]msgPointer to the messages to be compressed. Messages must be pre-processed per SHE specification if they do not already meet the full 128-bit block size requirement.
[in]msgLenThe number of 128 bit messages to be compressed.
[out]mpCompressPointer to the 128 bit buffer storing the compressed data.
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 1097 of file csec_driver.c.

status_t CSEC_DRV_VerifyMAC ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
const uint8_t *  mac,
uint16_t  macLen,
bool *  verifStatus,
uint32_t  timeout 
)

Verifies the MAC of a given message using CMAC with AES-128.

This function verifies the MAC of a given message using CMAC with AES-128.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer.
[in]msgLenNumber of bits of message on which CMAC will be computed.
[in]macPointer to the buffer containing the CMAC to be verified.
[in]macLenNumber of bits of the CMAC to be compared. A macLength value of zero indicates that all 128-bits are compared.
[out]verifStatusStatus of MAC verification command (true: verification operation passed, false: verification operation failed).
[in]timeoutTimeout in milliseconds.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 487 of file csec_driver.c.

status_t CSEC_DRV_VerifyMACAddrMode ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
const uint8_t *  mac,
uint16_t  macLen,
bool *  verifStatus 
)

Verifies the MAC of a given message (located in Flash) using CMAC with AES-128.

This function verifies the MAC of a given message using CMAC with AES-128. It is different from the CSEC_DRV_VerifyMAC function in the sense that it does not involve an extra copy of the data on which the CMAC is computed and the message pointer should be a pointer to Flash memory.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer (pointing to Flash memory).
[in]msgLenNumber of bits of message on which CMAC will be computed.
[in]macPointer to the buffer containing the CMAC to be verified.
[in]macLenNumber of bits of the CMAC to be compared. A macLength value of zero indicates that all 128-bits are compared.
[out]verifStatusStatus of MAC verification command (true: verification operation passed, false: verification operation failed).
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 550 of file csec_driver.c.

status_t CSEC_DRV_VerifyMACAsync ( csec_key_id_t  keyId,
const uint8_t *  msg,
uint32_t  msgLen,
const uint8_t *  mac,
uint16_t  macLen,
bool *  verifStatus 
)

Asynchronously verifies the MAC of a given message using CMAC with AES-128.

This function verifies the MAC of a given message using CMAC with AES-128, in an asynchronous manner.

Parameters
[in]keyIdKeyID used to perform the cryptographic operation.
[in]msgPointer to the message buffer.
[in]msgLenNumber of bits of message on which CMAC will be computed.
[in]macPointer to the buffer containing the CMAC to be verified.
[in]macLenNumber of bits of the CMAC to be compared. A macLength value of zero indicates that all 128-bits are compared.
[out]verifStatusStatus of MAC verification command (true: verification operation passed, false: verification operation failed).
Returns
STATUS_SUCCESS if the command was successfully launched, STATUS_BUSY if another command was already launched. CSEC_DRV_GetAsyncCmdStatus can be used in order to check the execution status.

Definition at line 1348 of file csec_driver.c.