ica_aes_gcm_kma_update

Purpose

Perform encryption of plain text or decryption of cipher text with authentication, depending on the direction specified in ica_aes_gcm_kma_init(). It also processes optional additional authenticated data (parameter aad). It can be used either for a single call when all aad data and the complete plain text or cipher text is known. Or it can also be used for processing chunks of aad data, and chunks of plain text or cipher text.

Each chunk of plain text or cipher text from parameter in_data or each chunk of data from aad must be a multiple of the AES block size (16 bytes), except of the last one.

If any chunk from aad or in_data is not a multiple of 16, the application must indicate this either in parameter end_of_aad or end_of_data. When end_of_aad was indicated, no more additional authenticated data can be provided. When end_of_data was indicated, no more message data can be provided. The process ends when both, end_of_aad and end_of_data are set.

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

int ica_aes_gcm_kma_update(const unsigned char *in_data,
  unsigned char *out_data, 
  unsigned long data_length,
  const unsigned char *aad, 
  unsigned long aad_length, 
  unsigned int end_of_aad, 
  unsigned int end_of_data,
  const 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

const unsigned char *in_data

Pointer to a readable buffer of size greater than or equal to data_length bytes. If direction = 1, parameter in_data must contain a payload message of size data_length that is encrypted and authenticated. If direction = 0, parameter in_data must contain an encrypted message that is decrypted and verified.

unsigned char *out_data

Pointer to a writable buffer of size data_length bytes or greater. If direction = 1, then the encrypted message from parameter in_data is written to that buffer. If direction = 0, then the decrypted message from the in_data buffer is written to that buffer. The pointer to out_data may point to the same buffer as for in_data, or a part of it, if you want to encrypt/decrypt in place.

unsigned long data_length

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

const unsigned char *aad

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

unsigned long aad_length

Length, in bytes, of the additional authenticated data in parameter aad. It must be 0 or greater, and less than 2⁶¹.

unsigned int end_of_aad

Can be either 0 or 1:

0

The application indicates that the current content of aad is not the last chunk of additional authenticated data. In this case, the value of aad_length must be a multiple of the AES block size (16 bytes).

1

The application indicates that the current content of aad is a single chunk or the last chunk. Or the application indicates that the last aad chunk has been provided in an earlier call to a ica_aes_gcm_kma function. In this case, parameter aad_length can have any non-negative value.

When both, end_of_aad and end_of_data are specified, the process ends.

unsigned int end_of_data

Can be either 0 or 1:

0

The application indicates that the current content of in_data is not the last chunk. In this case, the value of parameter data_length must be a multiple of the AES block size (16 bytes).

1

The application indicates that the current content of in_data is a single chunk or the last chunk. In this case, aad_length can have any non-negative value.

When both, end_of_aad and end_of_data are specified, the process ends.

const kma_ctx *ctx

Pointer to a previously initialized GCM context.

The input GCM context must be the resulting context of a preceding ica_aes_gcm_kma_init or ica_aes_gcm_kma_update function call. The resulting context can be used as the input to a subsequent ica_aes_gcm_kma_update, ica_aes_gcm_kma_get_tag or ica_aes_gcm_kma_verify_tag call.

Return codes

0

Success

EIO

If the operation fails.

For return codes indicating exceptions, see Return codes.