Detailed Description

Security Peripheral Abstraction Layer.

Data Structures

struct  security_user_config_t
 Define user configuration Implements : security_user_config_t_Class. More...
 

Enumerations

enum  security_instance_t { SECURITY_INSTANCE0 = 0U }
 Define instances for SECURITY PAL Implements : security_instance_t_Class. More...
 
enum  security_key_id_t {
  SECURITY_SECRET_KEY = 0x0U, SECURITY_MASTER_ECU = 0x1U, SECURITY_BOOT_MAC_KEY = 0x2U, SECURITY_BOOT_MAC = 0x3U,
  SECURITY_KEY_1, SECURITY_KEY_2, SECURITY_KEY_3, SECURITY_KEY_4,
  SECURITY_KEY_5, SECURITY_KEY_6, SECURITY_KEY_7, SECURITY_KEY_8,
  SECURITY_KEY_9, SECURITY_KEY_10, SECURITY_KEY_11 = 0x14U, SECURITY_KEY_12,
  SECURITY_KEY_13, SECURITY_KEY_14, SECURITY_KEY_15, SECURITY_KEY_16,
  SECURITY_KEY_17
}
 Defines the security keys Implements : security_key_id_t_Class. More...
 
enum  security_boot_flavor_t { SECURITY_BOOT_STRICT = 0U, SECURITY_BOOT_SERIAL = 1U, SECURITY_BOOT_PARALLEL = 2U, SECURITY_BOOT_NOT_DEFINED = 3U }
 Defines the security boot flavor Implements : security_boot_flavor_t_Class. More...
 
enum  security_cmd_t {
  SECURITY_CMD_ENC_ECB = 1U, SECURITY_CMD_ENC_CBC, SECURITY_CMD_DEC_ECB, SECURITY_CMD_DEC_CBC,
  SECURITY_CMD_GENERATE_MAC, SECURITY_CMD_VERIFY_MAC, SECURITY_CMD_LOAD_KEY, SECURITY_CMD_LOAD_PLAIN_KEY,
  SECURITY_CMD_EXPORT_RAM_KEY, SECURITY_CMD_INIT_RNG, SECURITY_CMD_EXTEND_SEED, SECURITY_CMD_RND,
  SECURITY_CMD_BOOT_FAILURE, SECURITY_CMD_BOOT_OK, SECURITY_CMD_GET_ID, SECURITY_CMD_DBG_CHAL,
  SECURITY_CMD_DBG_AUTH
}
 Defines the security command Implements : security_cmd_t_Class. More...
 

Functions

status_t SECURITY_Init (security_instance_t instance, const security_user_config_t *config)
 Initializes the SECURITY module. More...
 
status_t SECURITY_Deinit (security_instance_t instance)
 De-initializes the SECURITY module. More...
 
status_t SECURITY_EncryptEcbBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, uint8_t *cipherText, uint32_t timeout)
 ECB Encryption. More...
 
status_t SECURITY_DecryptEcbBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, uint8_t *plainText, uint32_t timeout)
 ECB Decryption. More...
 
status_t SECURITY_EncryptCbcBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, const uint8_t *iv, uint8_t *cipherText, uint32_t timeout)
 CBC Decryption. More...
 
status_t SECURITY_DecryptCbcBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, const uint8_t *iv, uint8_t *plainText, uint32_t timeout)
 CBC Decryption. More...
 
status_t SECURITY_GenerateMacBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, uint8_t *cmac, uint32_t timeout)
 MAC Generation. More...
 
status_t SECURITY_VerifyMacBlocking (security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus, uint32_t timeout)
 MAC Verification. More...
 
status_t SECURITY_LoadKey (security_instance_t instance, security_key_id_t keyId, const uint8_t *m1, const uint8_t *m2, const uint8_t *m3, uint8_t *m4, uint8_t *m5, uint32_t timeout)
 Load Key. More...
 
status_t SECURITY_LoadPlainKey (security_instance_t instance, const uint8_t *plainKey, uint32_t timeout)
 Load Plain Key. More...
 
status_t SECURITY_ExportRamKey (security_instance_t instance, uint8_t *m1, uint8_t *m2, uint8_t *m3, uint8_t *m4, uint8_t *m5, uint32_t timeout)
 Export RAM key. More...
 
status_t SECURITY_ExtendSeed (security_instance_t instance, const uint8_t *entropy, uint32_t timeout)
 Initialize Random Number Generator. More...
 
status_t SECURITY_InitRng (security_instance_t instance, uint32_t timeout)
 Initialize Random Number Generator. More...
 
status_t SECURITY_GenerateRnd (security_instance_t instance, uint8_t *rnd, uint32_t timeout)
 Generate RND. More...
 
status_t SECURITY_GetId (security_instance_t instance, const uint8_t *challenge, uint8_t *uid, uint8_t *sreg, uint8_t *mac, uint32_t timeout)
 Get ID. More...
 
status_t SECURITY_SecureBoot (security_instance_t instance, uint32_t bootImageSize, const uint8_t *bootImagePtr, uint32_t timeout)
 Secure boot. More...
 
status_t SECURITY_BootFailure (security_instance_t instance, uint32_t timeout)
 Boot Failure. More...
 
status_t SECURITY_BootOk (security_instance_t instance, uint32_t timeout)
 Boot Ok. More...
 
status_t SECURITY_BootDefine (security_instance_t instance, uint32_t bootSize, security_boot_flavor_t bootFlavor, uint32_t timeout)
 Boot Define. More...
 
status_t SECURITY_DbgChal (security_instance_t instance, uint8_t *challenge, uint32_t timeout)
 Debug Challenge. More...
 
status_t SECURITY_DbgAuth (security_instance_t instance, const uint8_t *authorization, uint32_t timeout)
 Debug Authentification. More...
 
status_t SECURITY_MPCompress (security_instance_t instance, const uint8_t *msg, uint32_t msgLen, uint8_t *mpCompress, uint32_t timeout)
 Miyaguchi-Prenell Compression. More...
 
status_t SECURITY_GenerateTrnd (security_instance_t instance, uint8_t *trnd, uint32_t timeout)
 Generate True Random Number. More...
 
status_t SECURITY_CancelCommand (security_instance_t instance)
 Cancel Command. More...
 
status_t SECURITY_GetAsyncCmdStatus (security_instance_t instance)
 Get asynchronous command status. More...
 
status_t SECURITY_EncryptEcb (security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, uint8_t *cipherText)
 Encrypt ECB. More...
 
status_t SECURITY_DecryptEcb (security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, uint8_t *plainText)
 Decrypt ECB. More...
 
status_t SECURITY_EncryptCbc (security_instance_t instance, security_key_id_t keyId, const uint8_t *plainText, uint32_t msgLen, const uint8_t *iv, uint8_t *cipherText)
 Encrypt CBC. More...
 
status_t SECURITY_DecryptCbc (security_instance_t instance, security_key_id_t keyId, const uint8_t *cipherText, uint32_t msgLen, const uint8_t *iv, uint8_t *plainText)
 Decrypt CBC. More...
 
status_t SECURITY_GenerateMac (security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, uint8_t *cmac)
 Generate MAC. More...
 
status_t SECURITY_VerifyMac (security_instance_t instance, security_key_id_t keyId, const uint8_t *msg, uint64_t msgLen, const uint8_t *mac, uint16_t macLen, bool *verifStatus)
 Verify MAC. More...
 

Enumeration Type Documentation

Defines the security boot flavor Implements : security_boot_flavor_t_Class.

Enumerator
SECURITY_BOOT_STRICT 
SECURITY_BOOT_SERIAL 
SECURITY_BOOT_PARALLEL 
SECURITY_BOOT_NOT_DEFINED 

Definition at line 100 of file security_pal.h.

Defines the security command Implements : security_cmd_t_Class.

Enumerator
SECURITY_CMD_ENC_ECB 
SECURITY_CMD_ENC_CBC 
SECURITY_CMD_DEC_ECB 
SECURITY_CMD_DEC_CBC 
SECURITY_CMD_GENERATE_MAC 
SECURITY_CMD_VERIFY_MAC 
SECURITY_CMD_LOAD_KEY 
SECURITY_CMD_LOAD_PLAIN_KEY 
SECURITY_CMD_EXPORT_RAM_KEY 
SECURITY_CMD_INIT_RNG 
SECURITY_CMD_EXTEND_SEED 
SECURITY_CMD_RND 
SECURITY_CMD_BOOT_FAILURE 
SECURITY_CMD_BOOT_OK 
SECURITY_CMD_GET_ID 
SECURITY_CMD_DBG_CHAL 
SECURITY_CMD_DBG_AUTH 

Definition at line 112 of file security_pal.h.

Define instances for SECURITY PAL Implements : security_instance_t_Class.

Enumerator
SECURITY_INSTANCE0 

Definition at line 52 of file security_pal.h.

Defines the security keys Implements : security_key_id_t_Class.

Enumerator
SECURITY_SECRET_KEY 
SECURITY_MASTER_ECU 
SECURITY_BOOT_MAC_KEY 
SECURITY_BOOT_MAC 
SECURITY_KEY_1 
SECURITY_KEY_2 
SECURITY_KEY_3 
SECURITY_KEY_4 
SECURITY_KEY_5 
SECURITY_KEY_6 
SECURITY_KEY_7 
SECURITY_KEY_8 
SECURITY_KEY_9 
SECURITY_KEY_10 
SECURITY_KEY_11 
SECURITY_KEY_12 
SECURITY_KEY_13 
SECURITY_KEY_14 
SECURITY_KEY_15 
SECURITY_KEY_16 
SECURITY_KEY_17 

Definition at line 61 of file security_pal.h.

Function Documentation

status_t SECURITY_BootDefine ( security_instance_t  instance,
uint32_t  bootSize,
security_boot_flavor_t  bootFlavor,
uint32_t  timeout 
)

Boot Define.

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

Parameters
[in]instancesecurity module instance
[in]bootSizeNumber of blocks of 128-bit data to check on boot. Maximum size is 512kBytes.
[in]bootFlavorThe boot method.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Unsupported code if function is not available.

Definition at line 725 of file security_pal.c.

status_t SECURITY_BootFailure ( security_instance_t  instance,
uint32_t  timeout 
)

Boot Failure.

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

Parameters
[in]instancesecurity module instance
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 671 of file security_pal.c.

status_t SECURITY_BootOk ( security_instance_t  instance,
uint32_t  timeout 
)

Boot Ok.

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

Parameters
[in]instancesecurity module instance
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 698 of file security_pal.c.

status_t SECURITY_CancelCommand ( security_instance_t  instance)

Cancel Command.

Cancels a previously initiated command.

Parameters
[in]instancesecurity module instance
Returns
STATUS_SUCCES

Definition at line 874 of file security_pal.c.

status_t SECURITY_DbgAuth ( security_instance_t  instance,
const uint8_t *  authorization,
uint32_t  timeout 
)

Debug Authentification.

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

Parameters
[in]instancesecurity module instance
[in]authorizationPointer to the 128-bit buffer containing the authorization value.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 786 of file security_pal.c.

status_t SECURITY_DbgChal ( security_instance_t  instance,
uint8_t *  challenge,
uint32_t  timeout 
)

Debug Challenge.

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

Parameters
[in]instancesecurity module instance
[out]challengePointer to the 128-bit buffer where the challenge data will be stored.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 758 of file security_pal.c.

status_t SECURITY_DecryptCbc ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  msgLen,
const uint8_t *  iv,
uint8_t *  plainText 
)

Decrypt CBC.

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

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation.
[in]cipherTextPointer to the cipher text buffer.
[in]msgLenNumber 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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 1012 of file security_pal.c.

status_t SECURITY_DecryptCbcBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  msgLen,
const uint8_t *  iv,
uint8_t *  plainText,
uint32_t  timeout 
)

CBC Decryption.

Perform AES-128 decryption in CBC mode of the input cipher text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation
[in]cipherTextPointer to the cipher text buffer.
[in]msgLenNumber of bytes of plain text message to be encrypted. It is 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]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 342 of file security_pal.c.

status_t SECURITY_DecryptEcb ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  msgLen,
uint8_t *  plainText 
)

Decrypt ECB.

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

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation.
[in]cipherTextPointer to the cipher text buffer.
[in]msgLenNumber 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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 953 of file security_pal.c.

status_t SECURITY_DecryptEcbBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  cipherText,
uint32_t  msgLen,
uint8_t *  plainText,
uint32_t  timeout 
)

ECB Decryption.

Perform AES-128 decryption in ECB mode of the input cipher text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation
[in]cipherTextPointer to the cipher text buffer.
[in]msgLenNumber of bytes of plain text message to be encrypted. It is multiple of 16 bytes.
[out]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 281 of file security_pal.c.

status_t SECURITY_Deinit ( security_instance_t  instance)

De-initializes the SECURITY module.

This function de-initializes the requested SECURITY instance.

Parameters
[in]instancesecurity module instance
Returns
Error or success status returned by API

Definition at line 212 of file security_pal.c.

status_t SECURITY_EncryptCbc ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  msgLen,
const uint8_t *  iv,
uint8_t *  cipherText 
)

Encrypt CBC.

Asynchronously performs the AES-128 encryption in CBC mode of the input plain text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]msgLenNumber 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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 982 of file security_pal.c.

status_t SECURITY_EncryptCbcBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  msgLen,
const uint8_t *  iv,
uint8_t *  cipherText,
uint32_t  timeout 
)

CBC Decryption.

Perform AES-128 decryption in CBC mode of the input cipher text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation
[in]plainTextPointer to the plain text buffer. The buffer shall have the same size as the cipher text buffer.
[in]msgLenNumber of bytes of plain text message to be encrypted. It is multiple of 16 bytes.
[in]ivPointer to the initialization vector buffer.
[out]cipherTextPointer to the cipher text buffer.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 311 of file security_pal.c.

status_t SECURITY_EncryptEcb ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  msgLen,
uint8_t *  cipherText 
)

Encrypt ECB.

Asynchronously performs the AES-128 encryption in ECB mode of the input plain text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation.
[in]plainTextPointer to the plain text buffer.
[in]msgLenNumber 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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 924 of file security_pal.c.

status_t SECURITY_EncryptEcbBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  plainText,
uint32_t  msgLen,
uint8_t *  cipherText,
uint32_t  timeout 
)

ECB Encryption.

Perform AES-128 encryption in ECB mode of the input plain text buffer.

Parameters
[in]instancesecurity module instance
[in]keyIdKeyID used to perform the cryptographic operation
[in]plainTextPointer to the plain text buffer
[in]msgLenNumber of bytes of plain text message to be encrypted. It is multiple of 16 bytes.
[out]cipherTextPointer to the cipher text buffer. The buffer shall have the same size as the plain text buffer.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 251 of file security_pal.c.

status_t SECURITY_ExportRamKey ( security_instance_t  instance,
uint8_t *  m1,
uint8_t *  m2,
uint8_t *  m3,
uint8_t *  m4,
uint8_t *  m5,
uint32_t  timeout 
)

Export RAM key.

Exports the RAM_KEY into a format protected by SECRET_KEY.

Parameters
[in]instancesecurity module instance
[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.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 497 of file security_pal.c.

status_t SECURITY_ExtendSeed ( security_instance_t  instance,
const uint8_t *  entropy,
uint32_t  timeout 
)

Initialize Random Number Generator.

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]instancesecurity module instance
[in]entropypointer to a 128-bit buffer containing the entropy.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 528 of file security_pal.c.

status_t SECURITY_GenerateMac ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  msg,
uint64_t  msgLen,
uint8_t *  cmac 
)

Generate MAC.

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

Parameters
[in]instancesecurity module instance
[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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 1042 of file security_pal.c.

status_t SECURITY_GenerateMacBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  msg,
uint64_t  msgLen,
uint8_t *  cmac,
uint32_t  timeout 
)

MAC Generation.

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

Parameters
[in]instancesecurity module instance
[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]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 372 of file security_pal.c.

status_t SECURITY_GenerateRnd ( security_instance_t  instance,
uint8_t *  rnd,
uint32_t  timeout 
)

Generate RND.

Generates a vector of 128 random bits.

Parameters
[in]instancesecurity module instance
[out]rndPointer to a 128-bit buffer where the generated random number has to be stored.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 581 of file security_pal.c.

status_t SECURITY_GenerateTrnd ( security_instance_t  instance,
uint8_t *  trnd,
uint32_t  timeout 
)

Generate True Random Number.

Generates a vector of 128 random bits using TRNG.

Parameters
[in]instancesecurity module instance
[out]trndPointer to a 128-bit buffer where the generated random number is stored.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS. Unsupported code if function is not available.

Definition at line 846 of file security_pal.c.

status_t SECURITY_GetAsyncCmdStatus ( security_instance_t  instance)

Get asynchronous command status.

Checks the status of the execution of an asynchronous command.

Parameters
[in]instancesecurity module instance
Returns
Error Code after command execution; STATUS_BUSY if a command is still in progress.

Definition at line 899 of file security_pal.c.

status_t SECURITY_GetId ( security_instance_t  instance,
const uint8_t *  challenge,
uint8_t *  uid,
uint8_t *  sreg,
uint8_t *  mac,
uint32_t  timeout 
)

Get ID.

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

Parameters
[in]instancesecurity module instance
[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.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 609 of file security_pal.c.

status_t SECURITY_Init ( security_instance_t  instance,
const security_user_config_t config 
)

Initializes the SECURITY module.

This function initializes and enables the requested SECURITY instance.

Parameters
[in]instancesecurity module instance
[in]configpointer to security module configuration structure
Returns
Error or success status returned by API

Definition at line 156 of file security_pal.c.

status_t SECURITY_InitRng ( security_instance_t  instance,
uint32_t  timeout 
)

Initialize Random Number Generator.

Initializes the seed and derive a key for the PRNG.

Parameters
[in]instancesecurity module instance
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 555 of file security_pal.c.

status_t SECURITY_LoadKey ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  m1,
const uint8_t *  m2,
const uint8_t *  m3,
uint8_t *  m4,
uint8_t *  m5,
uint32_t  timeout 
)

Load Key.

Updates an internal key per the SHE specification.

Parameters
[in]instancesecurity module instance
[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 parameter is stored.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 438 of file security_pal.c.

status_t SECURITY_LoadPlainKey ( security_instance_t  instance,
const uint8_t *  plainKey,
uint32_t  timeout 
)

Load Plain Key.

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

Parameters
[in]instancesecurity module instance
[in]plainKeyPointer to the 128-bit buffer containing the key that needs to be copied in RAM_KEY slot.
[in]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution.

Definition at line 470 of file security_pal.c.

status_t SECURITY_MPCompress ( security_instance_t  instance,
const uint8_t *  msg,
uint32_t  msgLen,
uint8_t *  mpCompress,
uint32_t  timeout 
)

Miyaguchi-Prenell Compression.

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

Parameters
[in]instancesecurity module instance
[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]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 815 of file security_pal.c.

status_t SECURITY_SecureBoot ( security_instance_t  instance,
uint32_t  bootImageSize,
const uint8_t *  bootImagePtr,
uint32_t  timeout 
)

Secure boot.

The function loads the command processor firmware and memory slot data and then executes the SHE secure boot protocol.

Parameters
[in]instancesecurity module instance
[in]bootImageSizeBoot image size (in bytes).
[in]bootImagePtrBoot image start address.
Note
Address passed in this parameter must be 32 bit aligned.
Parameters
[in]timeoutTimeout in ms; the function returns STATUS_TIMEOUT if the command is not finished in the allocated period.
Returns
Error Code after command execution.

Definition at line 640 of file security_pal.c.

status_t SECURITY_VerifyMac ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  msg,
uint64_t  msgLen,
const uint8_t *  mac,
uint16_t  macLen,
bool *  verifStatus 
)

Verify MAC.

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

Parameters
[in]instancesecurity module instance
[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_BUSY if another command is in execution, otherwise STATUS_SUCCESS.

Definition at line 1074 of file security_pal.c.

status_t SECURITY_VerifyMacBlocking ( security_instance_t  instance,
security_key_id_t  keyId,
const uint8_t *  msg,
uint64_t  msgLen,
const uint8_t *  mac,
uint16_t  macLen,
bool *  verifStatus,
uint32_t  timeout 
)

MAC Verification.

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

Parameters
[in]instancesecurity module instance
[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]timeoutSpecifies the maximum time allowed for command completion, else STATUS_TIMEOUT is returned.
Returns
Error Code after command execution. Output parameters are valid if the error code is STATUS_SUCCESS.

Definition at line 404 of file security_pal.c.