ica_aes_ctr

Purpose

Encrypt or decrypt data with an AES key using Counter (CTR) mode, as described in NIST Special Publication 800-38A Chapter 6.5. With the counter mode, each message block of cipher block size (16 bytes for AES) is combined with a counter value of the same size during encryption and decryption.

Starting with an initial counter value to be combined with the first message block, subsequent counter values to be combined with subsequent message blocks are derived from preceding counter values by an increment function. The increment function used in ica_aes_ctr is an arithmetic increment without carry on the M least significant bits in the counter where M is a parameter to ica_aes_ctr.

Required hardware support

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

Parameters

const unsigned char *in_data

Pointer to a readable buffer that contains the message to be encrypted or decrypted. The size of the message in bytes is data_length. The size of this buffer must be at least as large as data_length.

unsigned char *out_data

Pointer to a writable buffer to contain the resulting encrypted or decrypted message. The size of this buffer in bytes must be at least as large as data_length.

unsigned long data_length

Length in bytes of the message to be encrypted or decrypted, which resides at the beginning of in_data.

const unsigned char *key

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 char *ctr

Pointer to a readable and writable buffer of the same size as the cipher block in bytes. ctr contains an initialization value for a counter function, and it is replaced by a new value. That new value can be used as an initialization value for a counter function in a chained ica_aes_ctr call with the same key, if the data_length used in the preceding call is a multiple of the cipher block size.

unsigned int ctr_width

A number M between 8 and the cipher block size in bits. The value is used by the counter increment function, which increments a counter value by incrementing without carry the least significant M bits of the counter value. The value must be a multiple of 8 and smaller than 64. When in FIPS mode, an additional counter overflow check is performed, so that the given data length divided by 64 is not greater than 2^M.

unsigned int direction

0

Use the decrypt function.

1

Use the encrypt function.

Return codes

0

Success

For return codes indicating exceptions, see Return codes.