ica_aes_gcm_initialize

Purpose

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

This function is blocked by default when running in FIPS mode, because in this case the initialization vector (IV) must be created internally using an approved random source. Applications may use function ica_aes_gcm_initialize_fips() instead.

Applications may also use API function ica_allow_external_gcm_iv_in_fips_mode() to allow or disallow the use of an external GCM initialization vector in FIPS mode. Allowing the use of an external IV in FIPS mode makes the GCM API non-approved. In this case the function performs normally, but is indicated as non-approved operation by setting return code errno to EPERM.

Format


unsigned int ica_aes_gcm_initialize(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.