sparkle-kmac.h File Reference

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

#include "sparkle-hash.h"

Go to the source code of this file.

Macros
#define	ESCH_256_KMAC_SIZE   ESCH_256_HASH_SIZE
	Default size of the output for XOEsch256-KMAC.
#define	ESCH_384_KMAC_SIZE   ESCH_384_HASH_SIZE
	Default size of the output for XOEsch384-KMAC.

Typedefs
typedef esch_256_hash_state_t	esch_256_kmac_state_t
	State information for the XOEsch256-KMAC incremental mode.
typedef esch_384_hash_state_t	esch_384_kmac_state_t
	State information for the XOEsch384-KMAC incremental mode.

Functions
void	esch_256_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 XOEsch256 XOF mode. More...
void	esch_256_kmac_init (esch_256_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 XOEsch256 XOF mode. More...
void	esch_256_kmac_absorb (esch_256_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental XOEsch256-KMAC state. More...
void	esch_256_kmac_set_output_length (esch_256_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental XOEsch256-KMAC state. More...
void	esch_256_kmac_squeeze (esch_256_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental XOEsch256-KMAC state. More...
void	esch_256_kmac_finalize (esch_256_kmac_state_t *state, unsigned char out[ESCH_256_KMAC_SIZE])
	Squeezes fixed-length data from an incremental XOEsch256-KMAC state and finalizes the KMAC process. More...
void	esch_384_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 XOEsch384 XOF mode. More...
void	esch_384_kmac_init (esch_384_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 XOEsch384 XOF mode. More...
void	esch_384_kmac_absorb (esch_384_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental XOEsch384-KMAC state. More...
void	esch_384_kmac_set_output_length (esch_384_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental XOEsch384-KMAC state. More...
void	esch_384_kmac_squeeze (esch_384_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental XOEsch384-KMAC state. More...
void	esch_384_kmac_finalize (esch_384_kmac_state_t *state, unsigned char out[ESCH_384_KMAC_SIZE])
	Squeezes fixed-length data from an incremental XOEsch384-KMAC state and finalizes the KMAC process. More...

Detailed Description

Keyed Message Authentication Code (KMAC) based on XOEsch256.

The KMAC mode provides a method to authenticate a sequence of bytes using XOEsch256 or XOEsch384 in XOF 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 XOEsch256-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 esch_256_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 XOEsch256 XOF mode.

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 esch_256_kmac_absorb	(	esch_256_kmac_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs more input data into an incremental XOEsch256-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

esch_256_kmac_init(), esch_256_kmac_squeeze()

void esch_256_kmac_finalize	(	esch_256_kmac_state_t *	state,
		unsigned char	out[ESCH_256_KMAC_SIZE]
	)

Squeezes fixed-length data from an incremental XOEsch256-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 ESCH_256_KMAC_SIZE bytes of squeezed data.

This function combines the effect of esch_256_kmac_set_output_length() and esch_256_kmac_squeeze() for convenience.

See Also

esch_256_kmac_squeeze(), esch_256_kmac_set_output_length()

void esch_256_kmac_init	(	esch_256_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 XOEsch256 XOF mode.

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

esch_256_kmac_update(), esch_256_kmac_squeeze()

void esch_256_kmac_set_output_length	(	esch_256_kmac_state_t *	state,
		size_t	outlen
	)

Sets the desired output length for an incremental XOEsch256-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

esch_256_kmac_squeeze()

void esch_256_kmac_squeeze	(	esch_256_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental XOEsch256-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 esch_256_kmac_set_output_length() before this function to set the desured output length. If that function has not been called, then this function will assume that the application wants arbitrary-length output.

See Also

esch_256_kmac_init(), esch_256_kmac_update(), esch_256_kmac_finalize()

void esch_384_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 XOEsch384 XOF mode.

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 esch_384_kmac_absorb	(	esch_384_kmac_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs more input data into an incremental XOEsch384-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

esch_384_kmac_init(), esch_384_kmac_squeeze()

void esch_384_kmac_finalize	(	esch_384_kmac_state_t *	state,
		unsigned char	out[ESCH_384_KMAC_SIZE]
	)

Squeezes fixed-length data from an incremental XOEsch384-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 ESCH_384_KMAC_SIZE bytes of squeezed data.

This function combines the effect of esch_384_kmac_set_output_length() and esch_384_kmac_squeeze() for convenience.

See Also

esch_384_kmac_squeeze(), esch_384_kmac_set_output_length()

void esch_384_kmac_init	(	esch_384_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 XOEsch384 XOF mode.

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

esch_384_kmac_update(), esch_384_kmac_squeeze()

void esch_384_kmac_set_output_length	(	esch_384_kmac_state_t *	state,
		size_t	outlen
	)

Sets the desired output length for an incremental XOEsch384-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

esch_384_kmac_squeeze()

void esch_384_kmac_squeeze	(	esch_384_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental XOEsch384-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 esch_384_kmac_set_output_length() before this function to set the desured output length. If that function has not been called, then this function will assume that the application wants arbitrary-length output.

See Also

esch_384_kmac_init(), esch_384_kmac_update(), esch_384_kmac_finalize()