AES XTS APIs - zpc/aes_xts.h

Edit online

In file zpc/xts_cbc.h, libzpc provides encryption APIs for the Advanced Encryption Standard (AES) block cipher in Xor-Encrypt-Xor-based Tweaked Stealing (XTS) mode of operation.

Data structures

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

struct zpc_aes_xts;

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_xts_alloc

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

Format:


int zpc_aes_xts_alloc ( 
    struct zpc_aes_xts **ctx );

Parameters:


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

Return codes:

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

zpc_aes_xts_decrypt

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

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

The 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. All chunk-lengths except the final one 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_xts_decrypt (
    struct zpc_aes_xts *ctx,
    unsigned char *pt,
    const unsigned char *ct,
    size_t ctlen);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS context object
output	pt	Pointer to a plaintext buffer
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_xts_encrypt

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

The ciphertext buffer must be large enough to store the resulting ciphertext which has the same length as the (padded) 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.

A plaintext may be encrypted chunk-wise. For every operation on a plaintext chunk, the same rules apply as for the one-shot encryption. All chunk-lengths except the final one 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_xts_encrypt (
    struct zpc_aes_xts *ctx,
    unsigned char *ct,
    const unsigned char *pt,
    size_t ptlen );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS context object
output	ct	Pointer to a ciphertext buffer
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_xts_free

Purpose: Free an AES-XTS 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_xts_free (
     struct zpc_aes_xts **ctx )

Parameters:


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

zpc_aes_xts_get_intermediate_iv

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

Format:


int zpc_aes_xts_get_intermediate_iv (
     struct zpc_aes_xts *ctx,
     unsigned char iv[16]);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS context object
output	iv	Application-provided buffer with 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_xts_set_intermediate_iv

Purpose: Set the intermediate initialization vector to be used in the context of an AES-XTS operation to support multipart operations with a second XTS context. An initial initialization vector must be set before by using the zpc_aes_xts_set_iv() API.

Format:


int zpc_aes_xts_set_intermediate_iv (
     struct zpc_aes_xts *ctx,
     const unsigned char iv[16]);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS 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_xts_set_iv

Purpose: Set the initialization vector calculated from the input tweak value to be used in the context of an AES-XTS operation.

Format:


int zpc_aes_xts_set_iv (
    struct zpc_aes_xts *ctx,
    const unsigned char *iv );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS context object
input	iv	Pointer to a 16 byte tweak value used to calculate the initialization vector for the operation

Return codes:

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

zpc_aes_xts_set_key

Purpose: Set the keys to be used in the context of an AES-XTS operation.

If a key (key1 or key2) 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_xts_set_key (
    struct zpc_aes_xts *ctx,
    struct zpc_aes_key *key1,
    struct zpc_aes_key *key2 );

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an AES-XTS context object
input	key1	Pointer to the first AES key object
input	key2	Pointer to the second AES key object

The API parameter key1 corresponds to Key₁ in the IEEE-1619-2018 standard, and API parameter key2 corresponds to Key₂.

Return codes:

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