HMAC APIs - zpc/hmac.h

In file zpc/hmac.h, libzpc provides message authentication APIs for the hash-based message authentication code (HMAC).

Data structures

The context of an HMAC operation is opaque for an application and is stored in objects of type

struct zpc_hmac;

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_hmac_alloc

Purpose: Allocate a new context for an HMAC operation.

Format:


int zpc_hmac_alloc (
    struct zpc_hmac **ctx);

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an HMAC context.

Return codes:

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

zpc_hmac_set_key

Purpose: Set the key to be used in the context of an HMAC operation.

Format:


int zpc_hmac_set_key (
    struct zpc_hmac *ctx, 
    struct zpc_hmac_key *key);

Parameters:


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

Return codes:

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

zpc_hmac_sign

Purpose: Perform an HMAC signing operation.

Format:


int zpc_hmac_sign (
    struct zpc_hmac *ctx, 
    unsigned char *mac, 
    size_t maclen, 
    const unsigned char *msg, 
    size_t msglen)

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an HMAC context.
input, output	mac	Pointer to a message authentication code (MAC). When set to NULL, this indicates that an internal intermediate MAC is calculated and further intermediate calls with additional data from input parameter msg may follow. If the mac parameter is not NULL, and the maclen parameter is a valid MAC length (dependent on the underlying hash function of the key), the final MAC is computed.
input	maclen	Length of the message authentication code in bytes.
input	msg	Pointer to a message.
input	msglen	Message length in bytes.

Return codes:

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

zpc_hmac_verify

Purpose: Perform an HMAC verify operation.

Format:


int zpc_hmac_verify (
    struct zpc_hmac *ctx, 
    const unsigned char *mac, 
    size_t maclen, 
    const unsigned char *msg, 
    size_t msglen)

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an HMAC context.
input, output	mac	Pointer to a message authentication code (MAC). If the mac parameter is NULL, then an intermediate verify operation is performed. If the mac parameter is not NULL, and the maclen parameter is a valid MAC length (dependent on the underlying hash function of the key), then the given MAC is checked for correctness.
input	maclen	Length of the message authentication code in bytes.
input	msg	Pointer to a message.
input	msglen	Message length in bytes.

Return codes:

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

zpc_hmac_free

Purpose: Free an HMAC context.

Format:


int zpc_hmac_free (
    struct zpc_hmac **ctx)

Parameters:


Direction	Name	Description
input, output	ctx	Pointer to an HMAC context .

Return codes:

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