ica_aes_gcm_kma_init

Edit online

Purpose

Initialize the GCM context as returned from ica_aes_gcm_kma_ctx_new() either for encryption (direction = 1) or decryption (direction = 0).

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_kma_init_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


int ica_aes_gcm_kma_init(unsigned int direction,
  const unsigned char *iv, 
  unsigned int iv_length,
  const unsigned char *key, 
  unsigned int key_length,
  kma_ctx *ctx);

Required hardware support

  • KIMD-GHASH
  • KM-AES-128, KM-AES-192, or KM-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 int direction
0
Use the decrypt function.
1
Use the encrypt function.
const unsigned char *iv
Pointer to a readable buffer that contains an initialization vector. The buffer size, in bytes, can be equal to the vector length (iv_length) or greater.
unsigned int iv_length
Length, in bytes, of the initialization vector in buffer iv. The value must be greater than 0 and less than 261. A length of 12 is recommended.
const unsigned char *key
Pointer to a valid AES key.
unsigned int key_length
Length of the AES key in bytes. 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.
kma_ctx *ctx
Pointer to a previously allocated GCM context. This buffer is internally used as a working area by all other ica_aes_gcm_kma API functions and must not be changed by the application. The ctx context must be established by calling ica_aes_gcm_ctx_new() before any call to any other ica_aes_gcm_kma function, and must be freed by calling ica_aes_gcm_ctx_free() after the last call to any ica_aes_gcm_kma function.

Return codes

0
Success
EIO
If the operation fails.

For return codes indicating exceptions, see Return codes.