HMAC key APIs - zpc/hmac_key.h

In file zpc/hmac_key.h, libzpc provides APIs for managing HMAC key objects.

Data structures

The HMAC key structure zpc_hmac_key is opaque for the application:

struct zpc_hmac_key;

Supported key types

The following variants of protected HMAC keys are supported:

retrieved from ultravisor (UV) retrievable secrets (denoted by the type keyword PVSECRET, where the PV stands for protected virtualization, and therefore sometimes shortly referred to as pvsecrets)
created from given clear key data
randomly generated via sysfs attributes protkey_hmac_512 and protkey_hmac_1024 in /sys/devices/virtual/misc/pkey/protkey. Each new read on one of these sysfs attributes provides a new key of the related type.

The zpc/hmac_key.h file defines the following constants for the supported key type:

# define ZPC_HMAC_KEY_TYPE_PVSECRET   9

Properties

The following hash functions to be used in the zpc_hmac_key_set_hash_function() API are defined:


typedef enum {
    ZPC_HMAC_HASHFUNC_NOT_SET = -2,
    ZPC_HMAC_HASHFUNC_INVALID = -1,
    ZPC_HMAC_HASHFUNC_SHA_224 = 0,
    ZPC_HMAC_HASHFUNC_SHA_256,
    ZPC_HMAC_HASHFUNC_SHA_384,
    ZPC_HMAC_HASHFUNC_SHA_512,
} zpc_hmac_hashfunc_t;

The remainder of this information unit describes the available APIs for managing HMAC keys.

zpc_hmac_key_alloc

Purpose: Allocate a new HMAC key object with reference count 1.

Format:


int zpc_hmac_key_alloc(
    struct zpc_hmac_key **key );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key

Return codes:

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

zpc_hmac_key_set_type

Purpose: Set the HMAC key type.

Format:


int zpc_hmac_key_set_type(
    struct zpc_hmac_key *key,
    int type );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key.
input	type	One type is supported: `ZPC_HMAC_KEY_TYPE_PVSECRET`.

Return codes:

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

zpc_hmac_key_set_hash_function

Purpose: Set the hash function to be used in the context of an HMAC operation. This hash function is also used if clear key data is imported later and needs to be hashed to form a block-sized key.

Format:


int zpc_hmac_key_set_hash_function(
    struct zpc_hmac_key *key, 
    zpc_hmac_hashfunc_t func );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key.
input	func	HMAC hash function: sha-224, sha-256, sha-384, or sha-512. See Data structures for how to define the desired hash function. The size of the HMAC key (64 bytes or 128 bytes) is given by the block size of the hash function: for sha224 and sha256, the key size is set to 64 bytes, for sha384 and sha512, the key size is set to 128 bytes.

Return codes:

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

zpc_hmac_key_import

Purpose: Import an HMAC protected key (from origin secure key or retrievable secret ID).

Format:


int zpc_hmac_key_import(
    struct zpc_hmac_key *key, 
    const unsigned char *origin,
    size_t originlen );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key.
input	origin	Pointer to an HMAC protected key (origin: secure key or retrievable secret).
input	originlen	HMAC key origin length in bytes.

Return codes:

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

zpc_hmac_key_import_clear

Purpose: Import an HMAC clear-key. Such keys have no persistent key part (secure key or secret ID) and can therefore not be re-derived in case of a WKVP mismatch.

Format:


int zpc_hmac_key_import_clear(
    struct zpc_hmac_key *key, 
    const unsigned char *clrkey,
    size_t keylen );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key.
input	clrkey	Pointer to an HMAC clear-key.
input	keylen	HMAC clear key length in bytes. According to the HMAC specification, keys shorter than the block size of the underlying hash function of the key are padded with zeroes on the right up to the hash function block size. Keys longer than the hash function block size are first hashed using this hash function and then padded with zeroes up to the block size.

Return codes:

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

zpc_hmac_key_export

Purpose: Export an HMAC protected key (from origin secure key or retrievable secret ID).

Format:


int zpc_hmac_key_export(
    struct zpc_hmac_key   *key, 
    unsigned char         *origin,
    size_t                originlen );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC key.
output	origin	Pointer to an HMAC protected key (from origin secure key or retrievable secret ID).
input, output	originlen	Pointer to a field containing the HMAC protected key length in bytes.

Return codes:

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

zpc_hmac_key_generate

Purpose: Generate a random HMAC protected-key.

Format:


int zpc_hmac_key_generate(
    struct zpc_hmac_key   *key );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC protected key.

Return codes:

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

zpc_hmac_key_free

Purpose: Decrease the reference count of an HMAC key object and free it, if the count reaches 0.

Format:


int zpc_hmac_key_free(
    struct zpc_hmac_key   **key );

Parameters:


Direction	Name	Description
input, output	key	Pointer to an HMAC protected key.