ica_aes_ccm

Purpose

Encrypt and authenticate or decrypt data and check authenticity of data with an AES key using Counter with Cipher Block Chaining Message Authentication Code (CCM) mode, as described in NIST Special Publication 800-38C. Formatting and counter functions are implemented according to NIST 800-38C Appendix A.

Required hardware support

• KMCTR-AES-128, KMCTR-AES-192, or KMCTR-AES-256
• KMAC-AES-128, KMAC-AES-192, or KMAC-AES-256

Parameters

unsigned char *payload

Pointer to a buffer of size greater than or equal to payload_length bytes. If direction is equal to 1, the payload buffer must be readable and contain a payload message of size payload_length to be encrypted. If direction is equal to 0, the payload buffer must be writable. If the authentication verification succeeds, the decrypted message in the most significant payload_length bytes of ciphertext_n_mac is written to this buffer. Otherwise, the contents of this buffer is undefined.

unsigned long payload_length

Length in bytes of the message to be encrypted or decrypted. This value can be 0 unless assoc_data_length is equal to 0.

unsigned char *ciphertext_n_mac

Pointer to a buffer of size greater than or equal to payload_length plus mac_length bytes. If direction is equal to 1, the buffer must be writable and the encrypted message from payload followed by the message authentication code for the nonce, the payload, and associated data are written to that buffer. If direction is equal to 0, then the buffer is readable and contains an encrypted message of length payload_length followed by a message authentication code of length mac_length.

unsigned int mac_length

Length in bytes of the message authentication code. Valid values are: 4, 6, 8, 10, 12, and 16.

const unsigned char *assoc_data

Pointer to a readable buffer of size greater than or equal to assoc_data_length bytes. The associated data in the most significant assoc_data_length bytes is subject to the authentication code computation, but is not encrypted.

unsigned long assoc_data_length

Length of the associated data in assoc_data. This value can be 0 unless payload_length is equal to 0.

const unsigned char *nonce

Pointer to readable buffer of size greater than or equal to nonce_length bytes, which contains a nonce (number used once) of size nonce_length bytes.

unsigned int nonce_length

Length of the nonce in bytes. Valid values are greater than 6 and less than 14.

const unsigned char *key

Specifies a pointer to a valid AES key.

unsigned int key_length

Length in bytes of the AES key. Supported sizes are 16, 24, and 32 for AES-128, AES-192 and AES-256 respectively. Therefore, you can use the definitions: AES_KEY_LEN128, AES_KEY_LEN192, and AES_KEY_LEN256.

unsigned int direction

0

Use the decrypt function.

1

Use the encrypt function.

Return codes

0

Success

EFAULT

If direction is equal to 0 and the verification of the message authentication code fails.

For return codes indicating exceptions, see Return codes.