S32 SDK

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, 16, cipherText);
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, 128, cmac);
if (stat != CSEC_NO_ERROR)
return false;
stat = CSEC_DRV_VerifyMAC(CSEC_RAM_KEY, msg, 128, cmac, 128, &verifStatus);
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...
 

Typedefs

typedef void(* csec_callback_t) (csec_cmd_t completedCmd, void *callbackParam)
 CSEc asynchronous command complete callback function type. More...
 

Enumerations

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)
 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)
 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)
 Performs the AES-128 encryption in CBC mode. More...
 
status_t CSEC_DRV_DecryptCBC (csec_key_id_t keyId, const uint8_t *cipherText, uint16_t length, const uint8_t *iv, uint8_t *plainText)
 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)
 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)
 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)
 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 *cipherText, uint16_t length, const uint8_t *iv, uint8_t *plainText)
 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 (csec_callback_t callbackFunc, void *callbackParam)
 Installs a callback function which will be invoked when an asynchronous command finishes its execution. More...
 

Typedef Documentation

typedef void(* csec_callback_t) (csec_cmd_t completedCmd, void *callbackParam)

CSEc asynchronous command complete callback function type.

Implements : csec_callback_t_Class

Definition at line 59 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 47 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 816 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 752 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 784 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 943 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 904 of file csec_driver.c.

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

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.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 278 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 1131 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 
)

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.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 202 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 1073 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 150 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 
)

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.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 238 of file csec_driver.c.

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

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 1101 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 
)

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.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 165 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 1045 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 590 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 676 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 
)

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.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 318 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 358 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 1161 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 713 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 1225 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 853 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 404 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 132 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 641 of file csec_driver.c.

void CSEC_DRV_InstallCallback ( csec_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 1598 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 501 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 554 of file csec_driver.c.

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

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.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 979 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 
)

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).
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 402 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 449 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 1190 of file csec_driver.c.