ica_aes_ctrlist

Edit online

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 the same size as the cipher block in bytes is combined with a counter value of the same size during encryption and decryption.

The ica_aes_ctrlist function assumes that a list n of precomputed counter values is provided, where n is the smallest integer that is less than or equal to the message size divided by the cipher block size. This function optimally uses IBM Z® hardware support for non-standard counter functions.

Format


unsigned int ica_aes_ctrlist(const unsigned char *in_data,
  unsigned char *out_data,
  unsigned long data_length,
  const unsigned char *key,
  unsigned int key_length,
  const unsigned char *ctrlist,
  unsigned int direction);

Required hardware support

KMCTR-DEAKMCTR-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.
Calls to ica_aes_ctrlist with the same key can be chained if:
  • With the possible exception of the last call in the chain the data_length used is a multiple of the cipher block size.
  • The ctrlist argument of each chained call contains a list of counters that follows the counters used in the preceding call.
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.
const unsigned char *ctrlist
Pointer to a readable buffer that is both of a size greater than or equal to data_length, and a multiple of the cipher block size (16 bytes for AES). ctrlist should contain a list of precomputed counter values, each of the same size as the cipher block.
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.