ica_aes_gcm_initialize_fips

Purpose

Start and initialize a new session of AES-GCM for stream cipher requests.

The ica_aes_gcm_initialize_fips() API creates the initialization vector internally using an approved random source and passes it back to the application in the iv output parameter. Therefore, the application must provide a writable buffer of sufficient length to receive the internal initialization vector. The minimum iv_length in FIPS mode is 12 bytes.

Format


unsigned int ica_aes_gcm_initialize_fips(const unsigned char *iv,
  unsigned int iv_length,
  unsigned char *key, 
  unsigned int key_length,
  unsigned char *icb, 
  unsigned char *ucb,
  unsigned char *subkey, 
  unsigned int direction);

Required hardware support

KM-AES-128, KM-AES-192 or KM-AES-256
KIMD-GHASH
KMCTR-AES-128, KMCTR_AES-192 or KMCTR-AES-256

If available, KMA-GCM-AES-128, KMA-GCM-AES-192, and KMA-GCM-AES-256 are used transparently for better performance.

Parameters

unsigned char *iv

Pointer to a readable buffer of size greater than or equal to iv_length bytes, that contains an initialization vector of size iv_length.

unsigned int iv_length

Length in bytes of the initialization vector in iv. It must be greater than 0 and less than 2⁶¹. A length of 12 is recommended.

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 macros: AES_KEY_LEN128, AES_KEY_LEN192, and AES_KEY_LEN256.

unsigned char *icb

Pointer to the initial counter block, which is a writable buffer of size AES_BLOCK_SIZE (16 bytes). This buffer is filled by ica_aes_gcm_initialize() and used in ica_aes_gcm_last() for the final tag computation.

unsigned char *ucb

Pointer to the usage counter block, which is a writable buffer of size AES_BLOCK_SIZE (16 bytes). This buffer is filled by ica_aes_gcm_initialize() and updated (increased) during the intermediate update operations.

unsigned char *subkey

Pointer to the subkey block, which is a writable buffer (subkey block) of size AES_BLOCK_SIZE (16 bytes). This buffer is filled by ica_aes_gcm_initialize() and used in ica_aes_gcm_intermediate() and ica_aes_gcm_last().

unsigned int direction

0: Verify message authentication code and decrypt encrypted payload.
1: Encrypt payload and compute message authentication code for the additional authenticated data and the payload.

Return codes

0: Success
EIO: If the operation fails.
EFAULT: If direction equals 0 and the verification of the message authentication code fails.

For return codes indicating exceptions, see Return codes.