xoodyak-kmac.h File Reference

Keyed Message Authentication Code (KMAC) based on Xoodyak. More...

#include "xoodyak-hash.h"
#include <stddef.h>

Go to the source code of this file.

Macros
#define	XOODYAK_KMAC_SIZE   XOODYAK_HASH_SIZE
	Default size of the output for Xoodyak-KMAC.

Typedefs
typedef xoodyak_hash_state_t	xoodyak_kmac_state_t
	State information for the Xoodyak-KMAC incremental mode.

Functions
void	xoodyak_kmac (const unsigned char *key, size_t keylen, const unsigned char *in, size_t inlen, const unsigned char *custom, size_t customlen, unsigned char *out, size_t outlen)
	Computes a KMAC value using the Xoodyak hash algorithm. More...
void	xoodyak_kmac_init (xoodyak_kmac_state_t *state, const unsigned char *key, size_t keylen, const unsigned char *custom, size_t customlen)
	Initializes an incremental KMAC state using the Xoodyak hash algorithm. More...
void	xoodyak_kmac_absorb (xoodyak_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental Xoodyak-KMAC state. More...
void	xoodyak_kmac_set_output_length (xoodyak_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental Xoodyak-KMAC state. More...
void	xoodyak_kmac_squeeze (xoodyak_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental Xoodyak-KMAC state. More...
void	xoodyak_kmac_finalize (xoodyak_kmac_state_t *state, unsigned char out[XOODYAK_KMAC_SIZE])
	Squeezes fixed-length data from an incremental Xoodyak-KMAC state and finalizes the KMAC process. More...

Detailed Description

Keyed Message Authentication Code (KMAC) based on Xoodyak.

The KMAC mode provides a method to authenticate a sequence of bytes using Xoodyak in hashing mode. The output is essentially equivalent to hashing the key followed by the data.

NIST SP 800-185 is an extension of the XOF modes SHAKE128 and SHAKE256. The nearest equivalent for us is Xoodyak-XOF. We use the same encoding as NIST SP 800-185 to provide domain separation between the key and data.

References: NIST SP 800-185

Function Documentation

void xoodyak_kmac	(	const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	custom,
		size_t	customlen,
		unsigned char *	out,
		size_t	outlen
	)

Computes a KMAC value using the Xoodyak hash algorithm.

Parameters

key	Points to the key.
keylen	Number of bytes in the key.
in	Points to the data to authenticate.
inlen	Number of bytes of data to authenticate.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.
out	Buffer to receive the output KMAC value.
outlen	Length of the output KMAC value.

The customization string allows the application to perform domain separation between different uses of the KMAC algorithm.

void xoodyak_kmac_absorb	(	xoodyak_kmac_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs more input data into an incremental Xoodyak-KMAC state.

Parameters

state	KMAC state to be updated.
in	Points to the input data to be absorbed into the state.
inlen	Length of the input data to be absorbed into the state.

See Also

xoodyak_kmac_init(), xoodyak_kmac_squeeze()

void xoodyak_kmac_finalize	(	xoodyak_kmac_state_t *	state,
		unsigned char	out[XOODYAK_KMAC_SIZE]
	)

Squeezes fixed-length data from an incremental Xoodyak-KMAC state and finalizes the KMAC process.

Parameters

state	KMAC state to squeeze the output data from.
out	Points to the output buffer to receive the XOODYAK_KMAC_SIZE bytes of squeezed data.

This function combines the effect of xoodyak_kmac_set_output_length() and xoodyak_kmac_squeeze() for convenience.

See Also

xoodyak_kmac_squeeze(), xoodyak_kmac_set_output_length()

void xoodyak_kmac_init	(	xoodyak_kmac_state_t *	state,
		const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	custom,
		size_t	customlen
	)

Initializes an incremental KMAC state using the Xoodyak hash algorithm.

Parameters

state	Points to the state to be initialized.
key	Points to the key.
keylen	Number of bytes in the key.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.

See Also

xoodyak_kmac_update(), xoodyak_kmac_squeeze()

void xoodyak_kmac_set_output_length	(	xoodyak_kmac_state_t *	state,
		size_t	outlen
	)

Sets the desired output length for an incremental Xoodyak-KMAC state.

Parameters

state	KMAC state to squeeze the output data from after the desired output length has been set.
outlen	Desired output length, or zero for arbitrary-length output.

See Also

xoodyak_kmac_squeeze()

void xoodyak_kmac_squeeze	(	xoodyak_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental Xoodyak-KMAC state.

Parameters

state	KMAC state to squeeze the output data from.
out	Points to the output buffer to receive the squeezed data.
outlen	Number of bytes of data to squeeze out of the state.

The application should call xoodyak_kmac_set_output_length() before this function to set the desired output length. If that function has not been called, then this function will assume that the application wants arbitrary-length output.

See Also

xoodyak_kmac_init(), xoodyak_kmac_update(), xoodyak_kmac_finalize()