ascon-kmac.h File Reference

Keyed Message Authentication Code (KMAC) based on ASCON-XOF. More...

#include "ascon-xof.h"

Go to the source code of this file.

Macros
#define	ASCON_KMAC_SIZE   ASCON_HASH_SIZE
	Default size of the output for ASCON-KMAC and ASCON-KMACA.

Typedefs
typedef ascon_xof_state_t	ascon_kmac_state_t
	State information for the ASCON-KMAC and ASCON-KMACA incremental modes.

Functions
void	ascon_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 ASCON-XOF. More...
void	ascon_kmac_init (ascon_kmac_state_t *state, const unsigned char *key, size_t keylen, const unsigned char *custom, size_t customlen)
	Initializes an incremental KMAC state using ASCON-XOF. More...
void	ascon_kmac_absorb (ascon_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental ASCON-KMAC state. More...
void	ascon_kmac_set_output_length (ascon_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental ASCON-KMAC state. More...
void	ascon_kmac_squeeze (ascon_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental ASCON-KMAC state. More...
void	ascon_kmac_finalize (ascon_kmac_state_t *state, unsigned char out[ASCON_KMAC_SIZE])
	Squeezes fixed-length data from an incremental ASCON-KMAC state and finalizes the KMAC process. More...
void	ascon_kmaca (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 ASCON-XOFA. More...
void	ascon_kmaca_init (ascon_kmac_state_t *state, const unsigned char *key, size_t keylen, const unsigned char *custom, size_t customlen)
	Initializes an incremental KMAC state using ASCON-XOFA. More...
void	ascon_kmaca_absorb (ascon_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental ASCON-KMACA state. More...
void	ascon_kmaca_set_output_length (ascon_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental ASCON-KMACA state. More...
void	ascon_kmaca_squeeze (ascon_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental ASCON-KMACA state. More...
void	ascon_kmaca_finalize (ascon_kmac_state_t *state, unsigned char out[ASCON_KMAC_SIZE])
	Squeezes fixed-length data from an incremental ASCON-KMACA state and finalizes the KMAC process. More...

Detailed Description

Keyed Message Authentication Code (KMAC) based on ASCON-XOF.

The KMAC mode provides a method to authenticate a sequence of bytes using ASCON 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 ASCON-XOF. We use the same encoding as NIST SP 800-185 to provide domain separation between the key and data.

Two versions of KMAC are provided: ASCON-KMAC based around ASCON-XOF, and ASCON-KMACA based around ASCON-XOFA.

References: NIST SP 800-185

Function Documentation

void ascon_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 ASCON-XOF.

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

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

ascon_kmac_init(), ascon_kmac_squeeze()

void ascon_kmac_finalize	(	ascon_kmac_state_t *	state,
		unsigned char	out[ASCON_KMAC_SIZE]
	)

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

This function combines the effect of ascon_kmac_set_output_length() and ascon_kmac_squeeze() for convenience.

See Also

ascon_kmac_squeeze(), ascon_kmac_set_output_length()

void ascon_kmac_init	(	ascon_kmac_state_t *	state,
		const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	custom,
		size_t	customlen
	)

Initializes an incremental KMAC state using ASCON-XOF.

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

ascon_kmac_update(), ascon_kmac_squeeze()

void ascon_kmac_set_output_length	(	ascon_kmac_state_t *	state,
		size_t	outlen
	)

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

ascon_kmac_squeeze()

void ascon_kmac_squeeze	(	ascon_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental ASCON-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 ascon_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

ascon_kmac_init(), ascon_kmac_update(), ascon_kmac_finalize()

void ascon_kmaca	(	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 ASCON-XOFA.

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

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

ascon_kmaca_init(), ascon_kmaca_squeeze()

void ascon_kmaca_finalize	(	ascon_kmac_state_t *	state,
		unsigned char	out[ASCON_KMAC_SIZE]
	)

Squeezes fixed-length data from an incremental ASCON-KMACA 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 ASCON_KMAC_SIZE bytes of squeezed data.

This function combines the effect of ascon_kmaca_set_output_length() and ascon_kmaca_squeeze() for convenience.

See Also

ascon_kmaca_squeeze(), ascon_kmaca_set_output_length()

void ascon_kmaca_init	(	ascon_kmac_state_t *	state,
		const unsigned char *	key,
		size_t	keylen,
		const unsigned char *	custom,
		size_t	customlen
	)

Initializes an incremental KMAC state using ASCON-XOFA.

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

ascon_kmaca_update(), ascon_kmaca_squeeze()

void ascon_kmaca_set_output_length	(	ascon_kmac_state_t *	state,
		size_t	outlen
	)

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

ascon_kmaca_squeeze()

void ascon_kmaca_squeeze	(	ascon_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental ASCON-KMACA 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 ascon_kmaca_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

ascon_kmaca_init(), ascon_kmaca_update(), ascon_kmaca_finalize()