AES GCM APIs - zpc/aes_gcm.h

Edit online

In file zpc/aes_gcm.h, libzpc provides APIs for processing Advanced Encryption Standard (AES) block cipher in Galois/Counter Mode (GCM) mode of operation.

Data structures

The context of an AES-GCM operation is opaque for an application and is stored in objects of type

struct zpc_aes_gcm;

Context objects must not be shared among multiple threads. They may be used for multiple operations by setting or resetting the key or initialization vector.

zpc_aes_gcm_alloc

Purpose: Allocate a new context object for an AES-GCM operation.

Format:


int zpc_aes_gcm_alloc ( 
    struct zpc_aes_gcm **ctx );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_gcm_create_iv

Purpose: Create the initialization vector to be used in the context of an AES-GCM operation. The minimum and recommended length of the initialization vector is 12 bytes.

When an internal initialization vector is created, this GCM context can only be used for encryption using this initialization vector. The returned initialization vector is intended to be used in a second context for decryption.

Format:


int zpc_aes_gcm_create_iv (
    struct zpc_aes_gcm *ctx,
    unsigned char *iv,
    size_t ivlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object
input, output	iv	Pointer to an application-provided buffer of at least ivlen bytes to receive the internally created initialization vector
input	ivlen	Initialization vector length [bytes]

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_gcm_decrypt

Purpose: Decrypt a ciphertext to obtain the corresponding plaintext and verify the message authentication code of the ciphertext and additional data using AES-GCM. If there is no ciphertext input, the operation corresponds to AES-GMAC.

The plaintext buffer must be large enough to store the resulting plaintext which has the same length as the ciphertext. Plaintext and ciphertext buffer may be equal such that the operation is done in-place. If the operation is not done in-place, plaintext and ciphertext buffers must not overlap.

Additional data and ciphertext may be decrypted and authenticated chunk-wise. The additional data must be processed first. All chunk-lengths except the last one must be a multiple of 16 bytes. The ciphertext and message authentication code arguments must be NULL when processing those non-final chunks. A chunk-length that is not a multiple of 16 bytes, a non-NULL ciphertext argument, or a non-NULL message authentication code argument, indicates the end of the additional data. The ciphertext must be processed in the second place. All chunk-lengths except the last one must be a multiple of 16 bytes. The message authentication code argument must be NULL when processing those non-final chunks. A chunk-length that is not a multiple of 16 bytes, or a non-NULL message authentication code argument, indicates the end of the ciphertext. The same context object must be used to process all chunks without modifying it between operations.

Format:


int zpc_aes_gcm_decrypt (
    struct zpc_aes_gcm *ctx,  
    unsigned char  *pt,
    const unsigned char *mac,
    size_t maclen,
    const unsigned char *aad,
    size_t aadlen,
    const unsigned char *ct,
    size_t ctlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object
output	pt	Pointer to a plaintext buffer
input	mac	Pointer to a message authentication code buffer
input	maclen	Message authentication code length [bytes]
input	aad	Pointer to additional authenticated data buffer
input	aadlen	Additional authenticated data length [bytes]
input	ct	Pointer to a ciphertext buffer
input	ctlen	Ciphertext length [bytes]

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_gcm_encrypt

Purpose: Encrypt a plaintext and sign the ciphertext and additional data using AES-GCM to obtain the corresponding ciphertext and message authentication code. If there is no plaintext input, the operation corresponds to AES-GMAC.

The ciphertext buffer must be large enough to store the resulting ciphertext which has the same length as the plaintext.

Plaintext and ciphertext buffer may be equal such that the operation is done in-place. If the operation is not done in-place, plaintext and ciphertext buffers must not overlap.

Additional data and plaintext may be encrypted and authenticated chunk-wise. The additional data must be processed first. All chunk-lengths except the last one must be a multiple of 16 bytes. The plaintext and message authentication code arguments must be NULL when processing those non-final chunks. A chunk-length that is not a multiple of 16 bytes, a non-NULL plaintext argument or a non-NULL message authentication code argument, indicate the end of the additional data. The plaintext must be processed second. All chunk-lengths except the last one must be a multiple of 16 bytes. The message authentication code argument must be NULL when processing those non-final chunks. A chunk-length that is not a multiple of 16 bytes or a non-NULL message authentication code argument, indicates the end of the plaintext. The same context object must be used to process all chunks without modifying it between operations.

Format:


int zpc_aes_gcm_encrypt (
    struct zpc_aes_gcm *ctx,
    unsigned char *ct,
    unsigned char *mac,
    size_t maclen,
    const unsigned char *aad,
    size_t aadlen,
    const unsigned char *pt,
    size_t ptlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object
output	ct	Pointer to a ciphertext buffer
output	mac	Pointer to a message authentication code buffer
input	maclen	Message authentication code length [bytes]
input	aad	Pointer to additional authenticated data buffer
input	aadlen	Additional authenticated data length [bytes]
input	pt	Pointer to a plaintext buffer
input	ptlen	Plaintext length [bytes]

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_gcm_free

Purpose: Free an AES-GCM context object.

If a key is set, the reference count of that key object is decremented. The context object argument is set to NULL.

Format:


void zpc_aes_gcm_free (
     struct zpc_aes_cbc **ctx );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object

zpc_aes_gcm_set_iv

Purpose: Set the initialization vector to be used in the context of an AES-GCM operation.

Format:


int zpc_aes_gcm_set_iv (
    struct zpc_aes_gcm *ctx,
    const unsigned char *iv,
    size_t ivlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object
input	iv	Pointer to an initialization vector buffer
input	ivlen	Initialization vector length [bytes]

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_gcm_set_key

Purpose: Set the key to be used in the context object of an AES-GCM operation.

If a key is already set, the reference count of that key object is decremented. The context's key reference is set to the key object argument. If the key object argument is not NULL, the reference count of that key object is incremented.

Format:


int zpc_aes_gcm_set_key (
    struct zpc_aes_gcm *ctx,
    struct zpc_aes_key *key );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-GCM context object
input	key	Pointer to an AES key object

Return codes:

0 on success. Otherwise, a non-zero error code is returned.