romulus-kmac.h File Reference

Keyed Message Authentication Code (KMAC) based on Romulus-H. More...

#include "romulus-xof.h"

Go to the source code of this file.

Macros
#define	ROMULUS_KMAC_SIZE   ROMULUS_HASH_SIZE
	Default size of the output for Romulus-H-KMAC.

Typedefs
typedef romulus_xof_state_t	romulus_kmac_state_t
	State information for the Romulus-H-KMAC incremental mode.

Functions
void	romulus_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 Romulus-H hash algorithm. More...
void	romulus_kmac_init (romulus_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 Romulus-H hash algorithm. More...
void	romulus_kmac_absorb (romulus_kmac_state_t *state, const unsigned char *in, size_t inlen)
	Absorbs more input data into an incremental Romulus-H-KMAC state. More...
void	romulus_kmac_set_output_length (romulus_kmac_state_t *state, size_t outlen)
	Sets the desired output length for an incremental Romulus-H-KMAC state. More...
void	romulus_kmac_squeeze (romulus_kmac_state_t *state, unsigned char *out, size_t outlen)
	Squeezes output data from an incremental Romulus-H-KMAC state. More...
void	romulus_kmac_finalize (romulus_kmac_state_t *state, unsigned char out[ROMULUS_KMAC_SIZE])
	Squeezes fixed-length data from an incremental Romulus-H-KMAC state and finalizes the KMAC process. More...

Detailed Description

Keyed Message Authentication Code (KMAC) based on Romulus-H.

The KMAC mode provides a method to authenticate a sequence of bytes using Romulus-H 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 Romulus-H-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 romulus_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 Romulus-H 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 romulus_kmac_absorb	(	romulus_kmac_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

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

romulus_kmac_init(), romulus_kmac_squeeze()

void romulus_kmac_finalize	(	romulus_kmac_state_t *	state,
		unsigned char	out[ROMULUS_KMAC_SIZE]
	)

Squeezes fixed-length data from an incremental Romulus-H-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 ROMULUS_KMAC_SIZE bytes of squeezed data.

This function combines the effect of romulus_kmac_set_output_length() and romulus_kmac_squeeze() for convenience.

See Also

romulus_kmac_squeeze(), romulus_kmac_set_output_length()

void romulus_kmac_init	(	romulus_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 Romulus-H 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

romulus_kmac_update(), romulus_kmac_squeeze()

void romulus_kmac_set_output_length	(	romulus_kmac_state_t *	state,
		size_t	outlen
	)

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

romulus_kmac_squeeze()

void romulus_kmac_squeeze	(	romulus_kmac_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an incremental Romulus-H-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 romulus_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

romulus_kmac_init(), romulus_kmac_update(), romulus_kmac_finalize()