AES Full-XTS key APIs - zpc/aes_xts_key.h

Edit online

In file zpc/aes_xts_key.h, libzpc provides APIs to generate and manage advanced encryption standard (AES) block cipher keys to be used in a full-XTS context in the available full-XTS cryptographic functions.

The standard AES-XTS cipher mode (XEX-based tweaked-codebook mode with ciphertext stealing) is a block cipher mode designed for data-at-rest encryption on storage devices, using two separate keys, one to encrypt and one to tweak each data block based on its position and sector number. Both keys together build the XTS key. In Full-XTS, you only need one key, which, however, contains both key parts within one full-XTS key blob, which fulfills both purposes (encrypt and tweak).

The AES full-XTS keys are only available since IBM® z17 ™. Applications which need to perform AES-XTS operations on earlier machines must use the AES-XTS APIs with two separate AES keys (see AES XTS APIs - zpc/aes_xts.h).

Data structures

The AES full-XTS key structure is opaque for the application:

struct zpc_aes_xts_key;

Supported key types

The zpc/aes_xts_key.h file defines the following constants for the supported key types:


typedef enum {
    ZPC_XTS_SECRET_TYPE_NOT_SET = -2,
    ZPC_XTS_SECRET_TYPE_INVALID = -1,
    ZPC_XTS_SECRET_AES_XTS_128 = 0x07,     
    ZPC_XTS_SECRET_AES_XTS_256 = 0x08,
} zpc_xtssecret_type_t;

The remainder of this information unit describes the available APIs for managing AES Full-XTS keys.

zpc_aes_xts_key_alloc

Purpose: Allocate a new AES full-XTS key object with reference count 1.

Format:


int zpc_aes_xts_key_alloc (
    struct zpc_aes_xts_key **key)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS key object.

Return codes:

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

zpc_aes_xts_key_set_size

Purpose: Set the size of an AES full-XTS key.

Format:


int zpc_aes_xts_key_set_size (
    struct zpc_aes_xts_key *key, 
    int size)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS key object.
input	size	Key size in bits. Possible values are 128 or 256.

Return codes:

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

zpc_aes_xts_key_set_type

Purpose:

Format:


int zpc_aes_xts_key_set_type (
    struct zpc_aes_xts_key *key, 
    int type);

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS key object.
input	type	The type of the key. Valid value: ZPC_AES_XTS_KEY_TYPE_PVSECRET.

Return codes:

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

zpc_aes_xts_key_import

Purpose: Import an AES-XTS protected key (from origin secure key or retrievable secret).

Format:


int zpc_aes_xts_key_import (
    struct zpc_aes_xts_key *key, 
    const unsigned char *origin, 
    size_t originlen)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS protected key object.
input	origin	Pointer to an AES full-XTS protected key (origin: secure key or retrievable secret). Valid value: ZPC_AES_XTS_KEY_TYPE_PVSECRET
input	originlen	Length of the AES full-XTS protected key in bytes.

Return codes:

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

zpc_aes_xts_key_import_clear

Purpose: Import an AES XTS clear key into an AES full-XTS protected key.

Format:


int zpc_aes_xts_key_import_clear (
    struct zpc_aes_xts_key *key, 
    const unsigned char *clrkey)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS protected key object. If the key object has no type set, a full-XTS protected key is created from the given key material. If the type is set to ZPC_AES_XTS_KEY_TYPE_PVSECRET, then the import is not possible.
input	clrkey	Pointer to an AES full-XTS protected key object. The application must provide concatenated key material for two single AES keys of the specified size, that is, either 2 x 16 bytes or 2 x 32 bytes.

Return codes:

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

zpc_aes_xts_key_export

Purpose: Export an AES-XTS protected key (from origin secure key or retrievable secret).

Format:


int zpc_aes_xts_key_export (
     struct zpc_aes_xts_key *key, 
     unsigned char *origin, 
     size_t *originlen)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS protected key object.
input	origin	Pointer to an AES full-XTS protected key (origin: secure key or retrievable secret).
input	originlen	Pointer to a field containing the length of the AES full-XTS protected key in bytes.

Return codes:

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

zpc_aes_xts_key_generate

Purpose: Generate an AES-XTS key. If the key object has no type set, a full-XTS random protected key is created. If the type is set to ZPC_AES_XTS_KEY_TYPE_PVSECRET, then a key generation is not possible.

Format:


int zpc_aes_xts_key_generate (
    struct zpc_aes_xts_key *key)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS protected key object.

Return codes:

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

zpc_aes_xts_key_free

Purpose: Decrease the reference count of an AES full-XTS key object and free it if, the count reaches 0.

Format:


void zpc_aes_xts_key_free (
     struct zpc_aes_xts_key **key)

Parameters:


Direction	Name	Description
input, output	key	Pointer to an AES full-XTS protected key object.