ica_aes_gcm_last

Purpose

Authenticate data or verify the authenticity of data with an AES key using the Galois/Counter Mode (GCM), as described in NIST Special Publication 800-38D. ica_aes_gcm_last() must be used to authenticate or verify the authenticity of a message for which all preceding parts were processed with ica_aes_gcm_intermediate().

When running in FIPS mode, and parameter direction = 1 (ENCRYPT), and the default behavior of only allowing an internally created initialization vector was changed by the application using ica_allow_external_gcm_iv_in_fips_mode(), then the function performs normally, but errno is set to EPERM to indicate that the function is used in a non-approved way.

Format


unsigned int ica_aes_gcm_last(unsigned char *icb, 
  unsigned long aad_length,
  unsigned long ciph_length, 
  unsigned char *tag,
  unsigned char *final_tag, 
  unsigned int final_tag_length,
  unsigned char *key, 
  unsigned int key_length,
  unsigned char *subkey, 
  unsigned int direction);

Required hardware support

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 *icb

Pointer to the initial counter block, which is a writable buffer that is created during ica_aes_gcm_initialize() and is used in ica_aes_gcm_last() for the final tag computation. The length of this counter block is AES_BLOCK_SIZE (16 bytes).

unsigned long aad_length

Overall length of authentication data, cumulated over all intermediate operations.

unsigned long ciph_length

Length in bytes of the overall ciphertext, cumulated over all intermediate operations.

unsigned char *tag

Contains the temporary hash/tag value computed during preceding ica_aes_gcm_initialize() and ica_aes_gcm_intermediate() calls.

unsigned char *final_tag

Pointer to a readable buffer of size greater than or equal to final_tag_length bytes. If direction is 1, the buffer is not used. If direction is 0, this message authentication code (tag) is verified with the message authentication code computed over the intermediate update operations.

unsigned int final_tag_length

Length in bytes of the final message authentication code (tag). Valid values are 4, 8, 12, 13, 14, 15, and 16.

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 *subkey

Pointer to a writable buffer generated in ica_aes_gcm_initialize() and used in ica_aes_gcm_intermediate() and ica_aes_gcm_last(). The length of this subkey block is AES_BLOCK_SIZE (16 bytes).

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 is equal to 0 and the verification of the message authentication code fails.

For return codes indicating exceptions, see Return codes.