ica_aes_gcm

Purpose

Encrypt data and authenticate data or decrypt data and check authenticity of data with an AES key using the Galois/Counter Mode (GCM), as described in NIST Special Publication 800-38D. If no message needs to be encrypted or decrypted and only authentication or authentication checks are requested, then this method implements the GMAC mode.

This function is blocked 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 functions ica_aes_gcm_initialize_fips(), ica_aes_gcm_intermediate(), and ica_aes_gcm_last() instead.

Format

unsigned int ica_aes_gcm(unsigned char *plaintext,
  unsigned long plaintext_length,
  unsigned char *ciphertext,
  const unsigned char *iv,
  unsigned int iv_length,
  const unsigned char *aad,
  unsigned long aad_length,
  unsigned char *tag,
  unsigned int tag_length,
  const unsigned char *key,
  unsigned int key_length,
  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 *plaintext

Pointer to a buffer of size greater than or equal to plaintext_length bytes. If direction is equal to 1, the plaintext buffer must be readable and contain a payload message of size plaintext_length to be encrypted. If direction is equal to 0, the plaintext buffer must be writable and if the authentication verification succeeds, the decrypted message in the most significant plaintext_length bytes of ciphertext is written to the buffer. Otherwise, the contents of the buffer are undefined.

unsigned long plaintext_length

Length in bytes of the message to be encrypted or decrypted. This value can be 0 unless aad_length is equal to 0. The value must be greater than or equal to 0 and less than (2³⁶) - 32.

unsigned char *ciphertext

Pointer to a buffer of size greater than or equal to plaintext_length bytes. If direction is equal to 1, then this buffer must be writable and the encrypted message from plaintext is written to that buffer. If direction is equal to 0, then this buffer is readable and contains an encrypted message of length plaintext_length.

const unsigned char *iv

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

unsigned int iv_length

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

const unsigned char *aad

Pointer to a readable buffer of size greater than or equal to aad_length bytes. The additional authenticated data in the most significant aad_length bytes is subject to the message authentication code computation, but is not encrypted.

unsigned int aad_length

Length in bytes of the additional authenticated data in aad. The value must be greater than or equal to 0 and less than 2⁶¹.

unsigned char *tag

Pointer to a buffer of size greater than or equal to tag_length bytes. If direction is equal to 1, this buffer must be writable, and a message authentication code for the additional authenticated data in aad and the plain text in plaintext of size tag_length bytes is written to this buffer. If direction is equal to 0, this buffer must be readable and contain a message authentication code to be verified against the additional authenticated data in aad and the decrypted cipher text from ciphertext.

unsigned int tag_length

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

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.

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

EFAULT

If direction is equal to 0 and the verification of the message authentication code fails.

For return codes indicating exceptions, see Return codes.