ica_aes_gcm_kma_get_iv

Purpose

Obtain the initialization vector (IV) from the given context. This function is mainly intended to allow applications to query an internally created IV when running in FIPS mode. When encrypting, FIPS requires the internal creation of the IV using an approved random source. The internal IV can then be queried for use at decryption.

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_get_iv(const kma_ctx* ctx, 
  unsigned char *iv, 
  unsigned int *iv_length);

Required hardware support

None.

Parameters

const kma_ctx* ctx

Pointer to a GCM context.

unsigned char *iv

A writable buffer large enough to receive the initialization vector from the given context (ctx). Specifying NULL queries the size of the internal initialization vector. The size is then returned in parameter *iv_length.

unsigned int *iv_length

A pointer to an unsigned integer buffer indicating the size of the application-provided buffer to receive the internal IV from the GCM context (ctx).

Return codes

0

Success

EINVAL

If the GCM context (ctx) is NULL.

ENOMEM

If the IV length (*iv_length) is too small to receive the internal IV.

For return codes indicating exceptions, see Return codes.