AES CCM APIs - zpc/aes_ccm.h

Edit online

In file zpc/aes_ccm.h, libzpc provides authenticated encryption APIs for processing AES keys in CCM mode (counter with cipher block chaining message authentication code, or, abbreviated, counter with CBC-MAC).

The context of an AES-CCM operation is stored in objects of type struct zpc_aes_ccm. 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_ccm_alloc

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

Format:


int zpc_aes_ccm_alloc ( 
    struct zpc_aes_ccm **ctx );

Parameters:

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

Return codes:

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

zpc_aes_ccm_decrypt

Purpose: Decrypt a ciphertext verify the message authentication code of the corresponding plaintext and additional data using AES-CCM.

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.

Format:


int zpc_aes_ccm_decrypt (
    struct zpc_aes_ccm *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-CCM context object
output	pt	Pointer to the plaintext
input	mac	Pointer to the message authentication code
input	maclen	Message authentication code length [bytes]
input	aad	Pointer to additional authenticated data
input	aadlen	Additional authenticated data length [bytes]
input	ct	Pointer to the ciphertext
input	ctlen	Ciphertext length [bytes]

Return codes:

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

zpc_aes_ccm_encrypt

Purpose: Encrypt a plaintext and sign the plaintext and additional data using AES-CCM to obtain the corresponding ciphertext and message authentication code.

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.

Format:


int zpc_aes_ccm_encrypt (
    struct zpc_aes_ccm *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-CCM context object
output	ct	Pointer to the ciphertext
output	mac	Pointer to the message authentication code
input	maclen	Message authentication code length [bytes]
input	aad	Pointer to additional authenticated data
input	aadlen	Additional authenticated data length [bytes]
input	pt	Pointer to the plaintext
input	ptlen	Plaintext length [bytes]

Return codes:

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

zpc_aes_ccm_free

Purpose: Free an AES-CCM 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_ccm_free (
     struct zpc_aes_ccm **ctx );

Parameters:

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

zpc_aes_ccm_set_iv

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

Format:


int zpc_aes_ccm_set_iv (
    struct zpc_aes_ccm *ctx,
    const unsigned char *iv,
    size_t ivlen );

Parameters:

Direction	Name	Description
input, output	ctx	Pointer to an AES-CCM context object
input	iv	Pointer to an 7 - 13 byte initialization vector
input	ivlen	Initialization vector length [bytes]

Return codes:

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

zpc_aes_ccm_set_key

Purpose: Set the key to be used in the context of an AES-CCM 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_ccm_set_key (
    struct zpc_aes_ccm *ctx,
    struct zpc_aes_key *key );

Parameters:

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

Return codes:

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