AES CBC APIs - zpc/aes_cbc.h

In file zpc/aes_cbc.h, libzpc provides APIs for processing AES keys in Cipher Block Chaining (CBC) mode.

Data structures

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

struct zpc_aes_cbc;

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_cbc_alloc

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

Format:


int zpc_aes_cbc_alloc ( 
    struct zpc_aes_cbc **ctx );

Parameters:


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

Return codes:

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

zpc_aes_cbc_decrypt

Purpose: Decrypt a ciphertext using AES-CBC to obtain the corresponding plaintext.

The ciphertext buffer length must be a multiple of 16 bytes.

The plaintext buffer must be large enough to store the resulting plaintext which has the same length as the ciphertext. Removing any padding from the plaintext must be accomplished within the application.

Plaintext and ciphertext buffers 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.

A ciphertext may be decrypted chunk-wise. For every operation on a ciphertext chunk, the same rules apply as for the one-shot decryption. In particular, the chunk length must be a multiple of 16 bytes. The same context object must be used to decrypt all chunks without modifying it between operations.

Format:


int zpc_aes_cbc_decrypt (
    struct zpc_aes_cbc *ctx,
    unsigned char *pt,
    const unsigned char *ct,
    size_t ctlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-CBC context object
output	pt	Pointer to the plaintext
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_cbc_encrypt

Purpose: Encrypt a plaintext using AES-CBC to obtain the corresponding ciphertext.

The plaintext buffer length must be a multiple of 16 bytes. Padding the plaintext appropriately must be accomplished within the application.

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

Plaintext and ciphertext buffers 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.

A plaintext may be encrypted chunk-wise. For every operation on a plaintext chunk, the same rules apply as for the one-shot encryption. In particular, all chunk-lengths must be a multiple of 16 bytes. The same context object must be used to encrypt all chunks without modifying it between operations.

Format:


int zpc_aes_cbc_encrypt (
    struct zpc_aes_cbc *ctx,
    unsigned char *ct,
    const unsigned char *pt,
    size_t ptlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-CBC context object
output	ct	Pointer to the ciphertext
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_cbc_free

Purpose: Free an AES-CBC 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_cbc_free (
     struct zpc_aes_cbc **ctx );

Parameters:


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

zpc_aes_cbc_get_intermediate_iv

Purpose: Get the intermediate initialization vector to be used in the context of an AES-CBC operation to support multipart operations with a second CBC context. This is helpful when an application cannot retain the same context over a series of multipart operations.

Format:


int zpc_aes_cbc_get_intermediate_iv (
    struct zpc_aes_cbc *ctx,
    unsigned char iv[16] );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-CBC context object
output	iv	Application-provided buffer of 16 bytes size to receive the 16 byte intermediate initialization vector

Return codes:

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

zpc_aes_cbc_set_intermediate_iv

Purpose: Set the intermediate initialization vector to be used in the context of an AES-CBC operation to support multipart operations with a second CBC context.

An initial initialization vector must be set before by using the zpc_aes_cbc_set_iv() API.

Format:


int zpc_aes_cbc_set_intermediate_iv (
    struct zpc_aes_cbc *ctx,
    const unsigned char iv[16] );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-CBC context object
input	iv	Intermediate initialization vector with a length of 16 bytes

Return codes:

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

zpc_aes_cbc_set_iv

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

Format:


int zpc_aes_cbc_set_iv (
    struct zpc_aes_cbc *ctx,
    const unsigned char *iv );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-CBC context object
input	iv	Pointer to a 16 byte initialization vector

Return codes:

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

zpc_aes_cbc_set_key

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

Format:


int zpc_aes_cbc_set_key (
    struct zpc_aes_cbc *ctx,
    struct zpc_aes_key *key );

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.

Parameters:


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

Return codes:

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