ASCON-XOF and ASCON-XOFA extensible output functions (XOF's). More...

#include <ascon/permutation.h>
#include <ascon/utility.h>

Classes
struct	ascon_xof_state_t
	State information for ASCON-XOF incremental mode. More...

struct	ascon_xofa_state_t
	State information for ASCON-XOFA incremental mode. More...

class	ascon::xof_with_output_length< outlen >
	ASCON-XOF with a specific output length. More...

class	ascon::xofa_with_output_length< outlen >
	ASCON-XOFA with a specific output length. More...

Namespaces
	ascon

Macros
#define	ASCON_HASH_SIZE 32
	Size of the hash output for ASCON-HASH and the default hash output size for ASCON-XOF. More...

#define	ASCON_HASHA_SIZE ASCON_HASH_SIZE
	Size of the hash output for ASCON-HASHA and the default hash output size for ASCON-XOFA. More...

#define	ASCON_XOF_RATE 8
	Rate of absorbing and squeezing data for ASCON-XOF, ASCON-XOFA, ASCON-HASH, and ASCON-HASHA. More...

Typedefs
typedef xof_with_output_length< 0 >	ascon::xof
	ASCON-XOF object with arbitrary-length output. More...

typedef xofa_with_output_length< 0 >	ascon::xofa
	ASCON-XOFA object with arbitrary-length output. More...

Functions
void	ascon_xof (unsigned char out, const unsigned char in, size_t inlen)
	Hashes a block of input data with ASCON-XOF and generates a fixed-length 32 byte output. More...

void	ascon_xof_init (ascon_xof_state_t *state)
	Initializes the state for an ASCON-XOF hashing operation. More...

void	ascon_xof_init_fixed (ascon_xof_state_t *state, size_t outlen)
	Initializes the state for an incremental ASCON-XOF operation, with a fixed output length. More...

void	ascon_xof_init_custom (ascon_xof_state_t state, const char function_name, const unsigned char *custom, size_t customlen, size_t outlen)
	Initializes the state for an incremental ASCON-XOF operation, with a named function, customization string, and output length. More...

void	ascon_xof_reinit (ascon_xof_state_t *state)
	Re-initializes the state for an ASCON-XOF hashing operation. More...

void	ascon_xof_reinit_fixed (ascon_xof_state_t *state, size_t outlen)
	Re-initializes the state for an incremental ASCON-XOF operation, with a fixed output length. More...

void	ascon_xof_reinit_custom (ascon_xof_state_t state, const char function_name, const unsigned char *custom, size_t customlen, size_t outlen)
	Re-nitializes the state for an incremental ASCON-XOF operation, with a named function, customization string, and output length. More...

void	ascon_xof_free (ascon_xof_state_t *state)
	Frees the ASCON-XOF state and destroys any sensitive material. More...

void	ascon_xof_absorb (ascon_xof_state_t state, const unsigned char in, size_t inlen)
	Absorbs more input data into an ASCON-XOF state. More...

void	ascon_xof_squeeze (ascon_xof_state_t state, unsigned char out, size_t outlen)
	Squeezes output data from an ASCON-XOF state. More...

void	ascon_xof_pad (ascon_xof_state_t *state)
	Absorbs enough zeroes into an ASCON-XOF state to pad the input to the next multiple of the block rate. More...

void	ascon_xof_copy (ascon_xof_state_t dest, const ascon_xof_state_t src)
	Clones a copy of an ASCON-XOF state. More...

void	ascon_xofa (unsigned char out, const unsigned char in, size_t inlen)
	Hashes a block of input data with ASCON-XOFA and generates a fixed-length 32 byte output. More...

void	ascon_xofa_init (ascon_xofa_state_t *state)
	Initializes the state for an ASCON-XOFA hashing operation. More...

void	ascon_xofa_init_fixed (ascon_xofa_state_t *state, size_t outlen)
	Initializes the state for an incremental ASCON-XOFA operation, with a fixed output length. More...

void	ascon_xofa_init_custom (ascon_xofa_state_t state, const char function_name, const unsigned char *custom, size_t customlen, size_t outlen)
	Initializes the state for an incremental ASCON-XOFA operation, with a named function, customization string, and output length. More...

void	ascon_xofa_reinit (ascon_xofa_state_t *state)
	Re-initializes the state for an ASCON-XOFA hashing operation. More...

void	ascon_xofa_reinit_fixed (ascon_xofa_state_t *state, size_t outlen)
	Re-initializes the state for an incremental ASCON-XOFA operation, with a fixed output length. More...

void	ascon_xofa_reinit_custom (ascon_xofa_state_t state, const char function_name, const unsigned char *custom, size_t customlen, size_t outlen)
	Re-nitializes the state for an incremental ASCON-XOFA operation, with a named function, customization string, and output length. More...

void	ascon_xofa_free (ascon_xofa_state_t *state)
	Frees the ASCON-XOFA state and destroys any sensitive material. More...

void	ascon_xofa_absorb (ascon_xofa_state_t state, const unsigned char in, size_t inlen)
	Absorbs more input data into an ASCON-XOFA state. More...

void	ascon_xofa_squeeze (ascon_xofa_state_t state, unsigned char out, size_t outlen)
	Squeezes output data from an ASCON-XOFA state. More...

void	ascon_xofa_pad (ascon_xofa_state_t *state)
	Absorbs enough zeroes into an ASCON-XOFA state to pad the input to the next multiple of the block rate. More...

void	ascon_xofa_copy (ascon_xofa_state_t dest, const ascon_xofa_state_t src)
	Clones a copy of an ASCON-XOFA state. More...

Detailed Description

ASCON-XOF and ASCON-XOFA extensible output functions (XOF's).

References: https://ascon.iaik.tugraz.at/

Definition in file xof.h.

Macro Definition Documentation

◆ ASCON_HASH_SIZE

#define ASCON_HASH_SIZE 32

Size of the hash output for ASCON-HASH and the default hash output size for ASCON-XOF.

Examples: asconsum/asconsum.c.

Definition at line 43 of file xof.h.

◆ ASCON_HASHA_SIZE

#define ASCON_HASHA_SIZE ASCON_HASH_SIZE

Size of the hash output for ASCON-HASHA and the default hash output size for ASCON-XOFA.

Definition at line 49 of file xof.h.

◆ ASCON_XOF_RATE

#define ASCON_XOF_RATE 8

Rate of absorbing and squeezing data for ASCON-XOF, ASCON-XOFA, ASCON-HASH, and ASCON-HASHA.

Definition at line 55 of file xof.h.

Function Documentation

◆ ascon_xof()

void ascon_xof	(	unsigned char *	out,
		const unsigned char *	in,
		size_t	inlen
	)

Hashes a block of input data with ASCON-XOF and generates a fixed-length 32 byte output.

Parameters

out	Buffer to receive the hash output which must be at least 32 bytes in length.
in	Points to the input data to be hashed.
inlen	Length of the input data in bytes.

Use ascon_xof_squeeze() instead if you need variable-length XOF ouutput.

See also: ascon_xof_init(), ascon_xof_absorb(), ascon_xof_squeeze()

Definition at line 28 of file ascon-xof.c.

◆ ascon_xof_absorb()

void ascon_xof_absorb	(	ascon_xof_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs more input data into an ASCON-XOF state.

Parameters

state	XOF 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_xof_init(), ascon_xof_squeeze()

Examples: asconsum/asconsum.c.

Definition at line 228 of file ascon-xof.c.

◆ ascon_xof_copy()

void ascon_xof_copy	(	ascon_xof_state_t *	dest,
		const ascon_xof_state_t *	src
	)

Clones a copy of an ASCON-XOF state.

Parameters

dest	Destination XOF state to copy into.
src	Source XOF state to copy from.

The destination will be initialized by this operation, so it must not previously have been initialized or it has already been freed. The source must be already initialized.

Definition at line 344 of file ascon-xof.c.

◆ ascon_xof_free()

void ascon_xof_free ( ascon_xof_state_t * state )

Frees the ASCON-XOF state and destroys any sensitive material.

Parameters

state XOF state to be freed.

Examples: asconsum/asconsum.c.

Definition at line 218 of file ascon-xof.c.

◆ ascon_xof_init()

void ascon_xof_init ( ascon_xof_state_t * state )

Initializes the state for an ASCON-XOF hashing operation.

Parameters

state XOF state to be initialized.

See also: ascon_xof_absorb(), ascon_xof_squeeze(), ascon_xof()

Examples: asconsum/asconsum.c.

Definition at line 37 of file ascon-xof.c.

◆ ascon_xof_init_custom()

void ascon_xof_init_custom	(	ascon_xof_state_t *	state,
		const char *	function_name,
		const unsigned char *	custom,
		size_t	customlen,
		size_t	outlen
	)

Initializes the state for an incremental ASCON-XOF operation, with a named function, customization string, and output length.

Parameters

state	XOF state to be initialized.
function_name	Name of the function; e.g. "KMAC". May be NULL or empty for no function name.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

In the ASCON standard, the output length is encoded as a bit counter in a 32-bit word. If outlen is greater than 536870911, it will be replaced with zero to indicate arbitary-length output instead.

This version of initialization is intended for building higher-level functions like KMAC on top of ASCON-XOF. The function name provides domain separation between different functions. The customization string provides domain separation between different users of the same function.

See also: ascon_xof_init()

Definition at line 145 of file ascon-xof.c.

◆ ascon_xof_init_fixed()

void ascon_xof_init_fixed	(	ascon_xof_state_t *	state,
		size_t	outlen
	)

Initializes the state for an incremental ASCON-XOF operation, with a fixed output length.

Parameters

state	XOF state to be initialized.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

In the ASCON standard, the output length is encoded as a bit counter in a 32-bit word. If outlen is greater than 536870911, it will be replaced with zero to indicate arbitary-length output instead.

See also: ascon_xof_init()

Definition at line 74 of file ascon-xof.c.

◆ ascon_xof_pad()

void ascon_xof_pad ( ascon_xof_state_t * state )

Absorbs enough zeroes into an ASCON-XOF state to pad the input to the next multiple of the block rate.

Parameters

state XOF state to pad. Does nothing if the state is already aligned on a multiple of the block rate.

This function can avoid unnecessary XOR-with-zero operations to save some time when padding is required.

Definition at line 329 of file ascon-xof.c.

◆ ascon_xof_reinit()

void ascon_xof_reinit ( ascon_xof_state_t * state )

Re-initializes the state for an ASCON-XOF hashing operation.

Parameters

state XOF state to be re-initialized.

This function is equivalent to calling ascon_xof_free() and then ascon_xof_init() to restart the hashing process.

See also: ascon_xof_init()

Definition at line 183 of file ascon-xof.c.

◆ ascon_xof_reinit_custom()

void ascon_xof_reinit_custom	(	ascon_xof_state_t *	state,
		const char *	function_name,
		const unsigned char *	custom,
		size_t	customlen,
		size_t	outlen
	)

Re-nitializes the state for an incremental ASCON-XOF operation, with a named function, customization string, and output length.

Parameters

state	XOF state to be initialized.
function_name	Name of the function; e.g. "KMAC". May be NULL or empty for no function name.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

See also: ascon_xof_init_custom()

Definition at line 205 of file ascon-xof.c.

◆ ascon_xof_reinit_fixed()

void ascon_xof_reinit_fixed	(	ascon_xof_state_t *	state,
		size_t	outlen
	)

Re-initializes the state for an incremental ASCON-XOF operation, with a fixed output length.

Parameters

state	XOF state to be re-initialized.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

This function is equivalent to calling ascon_xof_free() and then ascon_xof_init_fixed() to restart the hashing process.

See also: ascon_xof_init_fixed()

Definition at line 194 of file ascon-xof.c.

◆ ascon_xof_squeeze()

void ascon_xof_squeeze	(	ascon_xof_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an ASCON-XOF state.

Parameters

state	XOF 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.

See also: ascon_xof_init(), ascon_xof_update()

Examples: asconsum/asconsum.c.

Definition at line 278 of file ascon-xof.c.

◆ ascon_xofa()

void ascon_xofa	(	unsigned char *	out,
		const unsigned char *	in,
		size_t	inlen
	)

Hashes a block of input data with ASCON-XOFA and generates a fixed-length 32 byte output.

Parameters

out	Buffer to receive the hash output which must be at least 32 bytes in length.
in	Points to the input data to be hashed.
inlen	Length of the input data in bytes.

Use ascon_xofa_squeeze() instead if you need variable-length XOF ouutput.

See also: ascon_xofa_init(), ascon_xofa_absorb(), ascon_xofa_squeeze()

Definition at line 26 of file ascon-xofa.c.

◆ ascon_xofa_absorb()

void ascon_xofa_absorb	(	ascon_xofa_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs more input data into an ASCON-XOFA state.

Parameters

state	XOF 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_xofa_init(), ascon_xofa_squeeze()

Examples: asconsum/asconsum.c.

Definition at line 226 of file ascon-xofa.c.

◆ ascon_xofa_copy()

void ascon_xofa_copy	(	ascon_xofa_state_t *	dest,
		const ascon_xofa_state_t *	src
	)

Clones a copy of an ASCON-XOFA state.

Parameters

dest	Destination XOF state to copy into.
src	Source XOF state to copy from.

The destination will be initialized by this operation, so it must not previously have been initialized or it has already been freed. The source must be already initialized.

Definition at line 343 of file ascon-xofa.c.

◆ ascon_xofa_free()

void ascon_xofa_free ( ascon_xofa_state_t * state )

Frees the ASCON-XOFA state and destroys any sensitive material.

Parameters

state XOF state to be freed.

Examples: asconsum/asconsum.c.

Definition at line 216 of file ascon-xofa.c.

◆ ascon_xofa_init()

void ascon_xofa_init ( ascon_xofa_state_t * state )

Initializes the state for an ASCON-XOFA hashing operation.

Parameters

state XOF state to be initialized.

See also: ascon_xofa_absorb(), ascon_xofa_squeeze(), ascon_xofa()

Examples: asconsum/asconsum.c.

Definition at line 35 of file ascon-xofa.c.

◆ ascon_xofa_init_custom()

void ascon_xofa_init_custom	(	ascon_xofa_state_t *	state,
		const char *	function_name,
		const unsigned char *	custom,
		size_t	customlen,
		size_t	outlen
	)

Initializes the state for an incremental ASCON-XOFA operation, with a named function, customization string, and output length.

Parameters

state	XOF state to be initialized.
function_name	Name of the function; e.g. "KMAC". May be NULL or empty for no function name.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

In the ASCON standard, the output length is encoded as a bit counter in a 32-bit word. If outlen is greater than 536870911, it will be replaced with zero to indicate arbitary-length output instead.

This version of initialization is intended for building higher-level functions like KMAC on top of ASCON-XOF. The function name provides domain separation between different functions. The customization string provides domain separation between different users of the same function.

See also: ascon_xofa_init()

Definition at line 143 of file ascon-xofa.c.

◆ ascon_xofa_init_fixed()

void ascon_xofa_init_fixed	(	ascon_xofa_state_t *	state,
		size_t	outlen
	)

Initializes the state for an incremental ASCON-XOFA operation, with a fixed output length.

Parameters

state	XOF state to be initialized.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

In the ASCON standard, the output length is encoded as a bit counter in a 32-bit word. If outlen is greater than 536870911, it will be replaced with zero to indicate arbitary-length output instead.

See also: ascon_xofa_init()

Definition at line 72 of file ascon-xofa.c.

◆ ascon_xofa_pad()

void ascon_xofa_pad ( ascon_xofa_state_t * state )

Absorbs enough zeroes into an ASCON-XOFA state to pad the input to the next multiple of the block rate.

Parameters

state XOF state to pad. Does nothing if the state is already aligned on a multiple of the block rate.

This function can avoid unnecessary XOR-with-zero operations to save some time when padding is required.

Definition at line 328 of file ascon-xofa.c.

◆ ascon_xofa_reinit()

void ascon_xofa_reinit ( ascon_xofa_state_t * state )

Re-initializes the state for an ASCON-XOFA hashing operation.

Parameters

state XOF state to be re-initialized.

This function is equivalent to calling ascon_xofa_free() and then ascon_xofa_init() to restart the hashing process.

See also: ascon_xof_init()

Definition at line 181 of file ascon-xofa.c.

◆ ascon_xofa_reinit_custom()

void ascon_xofa_reinit_custom	(	ascon_xofa_state_t *	state,
		const char *	function_name,
		const unsigned char *	custom,
		size_t	customlen,
		size_t	outlen
	)

Re-nitializes the state for an incremental ASCON-XOFA operation, with a named function, customization string, and output length.

Parameters

state	XOF state to be initialized.
function_name	Name of the function; e.g. "KMAC". May be NULL or empty for no function name.
custom	Points to the customization string.
customlen	Number of bytes in the customization string.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

See also: ascon_xofa_init_custom()

Definition at line 203 of file ascon-xofa.c.

◆ ascon_xofa_reinit_fixed()

void ascon_xofa_reinit_fixed	(	ascon_xofa_state_t *	state,
		size_t	outlen
	)

Re-initializes the state for an incremental ASCON-XOFA operation, with a fixed output length.

Parameters

state	XOF state to be re-initialized.
outlen	The desired output length in bytes, or 0 for arbitrary-length.

This function is equivalent to calling ascon_xofa_free() and then ascon_xofa_init_fixed() to restart the hashing process.

See also: ascon_xof_init_fixed()

Definition at line 192 of file ascon-xofa.c.

◆ ascon_xofa_squeeze()

void ascon_xofa_squeeze	(	ascon_xofa_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output data from an ASCON-XOFA state.

Parameters

state	XOF 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.

See also: ascon_xofa_init(), ascon_xofa_update()

Examples: asconsum/asconsum.c.

Definition at line 276 of file ascon-xofa.c.

Classes

Namespaces

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ASCON_HASH_SIZE

◆ ASCON_HASHA_SIZE

◆ ASCON_XOF_RATE

Function Documentation

◆ ascon_xof()

◆ ascon_xof_absorb()

◆ ascon_xof_copy()

◆ ascon_xof_free()

◆ ascon_xof_init()

◆ ascon_xof_init_custom()

◆ ascon_xof_init_fixed()

◆ ascon_xof_pad()

◆ ascon_xof_reinit()

◆ ascon_xof_reinit_custom()

◆ ascon_xof_reinit_fixed()

◆ ascon_xof_squeeze()

◆ ascon_xofa()

◆ ascon_xofa_absorb()

◆ ascon_xofa_copy()

◆ ascon_xofa_free()

◆ ascon_xofa_init()

◆ ascon_xofa_init_custom()

◆ ascon_xofa_init_fixed()

◆ ascon_xofa_pad()

◆ ascon_xofa_reinit()

◆ ascon_xofa_reinit_custom()

◆ ascon_xofa_reinit_fixed()

◆ ascon_xofa_squeeze()