ASCON-Prf, ASCON-PrfShort, and ASCON-Mac algorithms. More...

#include <ascon/permutation.h>

Classes
struct	ascon_prf_state_t
	State information for the ASCON-Prf incremental mode. More...

Macros
#define	ASCON_PRF_KEY_SIZE 16
	Size of the key for ASCON-Prf in bytes. More...

#define	ASCON_PRF_TAG_SIZE 16
	Default size of the ASCON-Prf output in bytes. More...

#define	ASCON_PRF_SHORT_KEY_SIZE ASCON_PRF_KEY_SIZE
	Size of the key for ASCON-PrfShort in bytes. More...

#define	ASCON_PRF_SHORT_MAX_INPUT_SIZE 16
	Maximum number of bytes that can be input to ASCON-PrfShort. More...

#define	ASCON_PRF_SHORT_MAX_OUTPUT_SIZE 16
	Maximum number of bytes that can be output from ASCON-PrfShort. More...

#define	ASCON_PRF_SHORT_TAG_SIZE ASCON_PRF_SHORT_MAX_OUTPUT_SIZE
	Default size of the ASCON-PrfShort output in bytes. More...

#define	ASCON_MAC_KEY_SIZE ASCON_PRF_KEY_SIZE
	Size of the key for ASCON-Mac in bytes. More...

#define	ASCON_MAC_TAG_SIZE ASCON_PRF_TAG_SIZE
	Size of the ASCON-Mac output in bytes. More...

Functions
void	ascon_prf (unsigned char out, size_t outlen, const unsigned char in, size_t inlen, const unsigned char *key)
	Processes a key and input data with ASCON-Prf to produce a tag. More...

void	ascon_prf_fixed (unsigned char out, size_t outlen, const unsigned char in, size_t inlen, const unsigned char *key)
	Processes a key and input data with ASCON-Prf to produce a fixed-length output tag. More...

int	ascon_prf_short (unsigned char out, size_t outlen, const unsigned char in, size_t inlen, const unsigned char *key)
	Processes a key and input data with ASCON-PrfShort to produce a tag. More...

void	ascon_mac (unsigned char tag, const unsigned char in, size_t inlen, const unsigned char *key)
	Processes a key and input data with ASCON-Mac to produce a tag. More...

int	ascon_mac_verify (const unsigned char tag, const unsigned char in, size_t inlen, const unsigned char *key)
	Verifies an ASCON-Mac tag value. More...

void	ascon_prf_init (ascon_prf_state_t state, const unsigned char key)
	Initializes the state for an incremental ASCON-Prf operation. More...

void	ascon_prf_fixed_init (ascon_prf_state_t state, const unsigned char key, size_t outlen)
	Initializes the state for an incremental ASCON-Prf operation with fixed-length output. More...

void	ascon_prf_reinit (ascon_prf_state_t state, const unsigned char key)
	Re-initializes the state for an incremental ASCON-Prf operation. More...

void	ascon_prf_fixed_reinit (ascon_prf_state_t state, const unsigned char key, size_t outlen)
	Re-initializes the state for an incremental ASCON-Prf operation with fixed-length output. More...

void	ascon_prf_free (ascon_prf_state_t *state)
	Frees the ASCON-Prf state and destroys any sensitive material. More...

void	ascon_prf_absorb (ascon_prf_state_t state, const unsigned char in, size_t inlen)
	Absorbs input data into an incremental ASCON-Prf state. More...

void	ascon_prf_squeeze (ascon_prf_state_t state, unsigned char out, size_t outlen)
	Squeezes output from an incremental ASCON-Prf operation. More...

Detailed Description

ASCON-Prf, ASCON-PrfShort, and ASCON-Mac algorithms.

ASCON-Prf is a pseudorandom function (PRF) built around the ASCON permutation. It provides a method to combine a 128-bit key and an arbitary amount of input to produce an arbitrary amount of output.

ASCON-Prf can be used as a lightweight key derivation function (KDF) in place of other options like ASCON-HKDF or ASCON-KMAC when the key is 128 bits in size.

ASCON-Mac wraps ASCON-Prf to turn it into a message authentication code (MAC) with an arbitrary amount of input and a fixed 128 bits of output. ASCON-Mac is identical to ASCON-Prf with an output length of 128 bits and also provides an API to verify authentication tags.

ASCON-PrfShort is a cut-down version of ASCON-Prf that is limited to a single block of input of 128 bits or less in size, and a single block of output of 128 bits or less in size.

ASCON-PrfShort is suitable for authenticating very small amounts of data in a single ASCON permutation call. It can also be used as a key derivation function (KDF) in protocols that derive 128-bit symmetric keys from a 128-bit master key, with the input being used for domain separation between the different derived keys.

References: https://eprint.iacr.org/2021/1574

Definition in file prf.h.

Macro Definition Documentation

◆ ASCON_MAC_KEY_SIZE

#define ASCON_MAC_KEY_SIZE ASCON_PRF_KEY_SIZE

Size of the key for ASCON-Mac in bytes.

Definition at line 95 of file prf.h.

◆ ASCON_MAC_TAG_SIZE

#define ASCON_MAC_TAG_SIZE ASCON_PRF_TAG_SIZE

Size of the ASCON-Mac output in bytes.

Definition at line 100 of file prf.h.

◆ ASCON_PRF_KEY_SIZE

#define ASCON_PRF_KEY_SIZE 16

Size of the key for ASCON-Prf in bytes.

Definition at line 65 of file prf.h.

◆ ASCON_PRF_SHORT_KEY_SIZE

#define ASCON_PRF_SHORT_KEY_SIZE ASCON_PRF_KEY_SIZE

Size of the key for ASCON-PrfShort in bytes.

Definition at line 75 of file prf.h.

◆ ASCON_PRF_SHORT_MAX_INPUT_SIZE

#define ASCON_PRF_SHORT_MAX_INPUT_SIZE 16

Maximum number of bytes that can be input to ASCON-PrfShort.

Definition at line 80 of file prf.h.

◆ ASCON_PRF_SHORT_MAX_OUTPUT_SIZE

#define ASCON_PRF_SHORT_MAX_OUTPUT_SIZE 16

Maximum number of bytes that can be output from ASCON-PrfShort.

Definition at line 85 of file prf.h.

◆ ASCON_PRF_SHORT_TAG_SIZE

#define ASCON_PRF_SHORT_TAG_SIZE ASCON_PRF_SHORT_MAX_OUTPUT_SIZE

Default size of the ASCON-PrfShort output in bytes.

Definition at line 90 of file prf.h.

◆ ASCON_PRF_TAG_SIZE

#define ASCON_PRF_TAG_SIZE 16

Default size of the ASCON-Prf output in bytes.

Definition at line 70 of file prf.h.

Function Documentation

◆ ascon_mac()

void ascon_mac	(	unsigned char *	tag,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	key
	)

Processes a key and input data with ASCON-Mac to produce a tag.

Parameters

tag	Buffer to receive the ASCON_PRF_TAG_SIZE bytes of the tag.
in	Points to the input data to be processed.
inlen	Length of the input data in bytes.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

This function operates ASCON-Prf in fixed-length output mode with the output length set to ASCON_PRF_TAG_SIZE.

See also: ascon_mac_verify(), ascon_prf()

Definition at line 85 of file ascon-prf.c.

◆ ascon_mac_verify()

int ascon_mac_verify	(	const unsigned char *	tag,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	key
	)

Verifies an ASCON-Mac tag value.

Parameters

tag	Buffer that contains the ASCON_PRF_TAG_SIZE bytes of the tag.
in	Points to the input data to be processed.
inlen	Length of the input data in bytes.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

Returns: 0 if the tag is correct or -1 if incorrect.

See also: ascon_mac(), ascon_prf()

Definition at line 97 of file ascon-prf.c.

◆ ascon_prf()

void ascon_prf	(	unsigned char *	out,
		size_t	outlen,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	key
	)

Processes a key and input data with ASCON-Prf to produce a tag.

Parameters

out	Buffer to receive the PRF tag which must be at least outlen bytes in length.
outlen	Length of the output buffer in bytes. Recommended to be ASCON_PRF_TAG_SIZE.
in	Points to the input data to be processed.
inlen	Length of the input data in bytes.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

This function operates ASCON-Prf in unlimited output mode, with the output truncated at outlen bytes.

See also: ascon_prf_fixed(), ascon_prf_short(), ascon_mac()

Definition at line 38 of file ascon-prf.c.

◆ ascon_prf_absorb()

void ascon_prf_absorb	(	ascon_prf_state_t *	state,
		const unsigned char *	in,
		size_t	inlen
	)

Absorbs input data into an incremental ASCON-Prf state.

Parameters

state	PRF state to be absorb.
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_prf_init(), ascon_prf_squeeze()

Definition at line 156 of file ascon-prf.c.

◆ ascon_prf_fixed()

void ascon_prf_fixed	(	unsigned char *	out,
		size_t	outlen,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	key
	)

Processes a key and input data with ASCON-Prf to produce a fixed-length output tag.

Parameters

out	Buffer to receive the PRF tag which must be at least outlen bytes in length.
outlen	Length of the output buffer in bytes. Recommended to be ASCON_PRF_TAG_SIZE.
in	Points to the input data to be processed.
inlen	Length of the input data in bytes.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

This function operates ASCON-Prf in fixed-length output mode, with the output length set at exactly outlen bytes.

See also: ascon_prf(), ascon_prf_short(), ascon_mac()

Definition at line 50 of file ascon-prf.c.

◆ ascon_prf_fixed_init()

void ascon_prf_fixed_init	(	ascon_prf_state_t *	state,
		const unsigned char *	key,
		size_t	outlen
	)

Initializes the state for an incremental ASCON-Prf operation with fixed-length output.

Parameters

state	PRF state to be initialized.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.
outlen	Number of bytes of output that is desired, or 0 for unlimited.

This function will set ASCON-Prf into unlimited output mode.

See also: ascon_prf_init(), ascon_prf_absorb(), ascon_prf_squeeze()

Definition at line 115 of file ascon-prf.c.

◆ ascon_prf_fixed_reinit()

void ascon_prf_fixed_reinit	(	ascon_prf_state_t *	state,
		const unsigned char *	key,
		size_t	outlen
	)

Re-initializes the state for an incremental ASCON-Prf operation with fixed-length output.

Parameters

state	PRF state to be re-initialized.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.
outlen	Number of bytes of output that is desired, or 0 for unlimited.

This function is equivalent to calling ascon_prf_free() and then ascon_prf_init() to restart the hashing process.

See also: ascon_prf_reinit(), ascon_prf_fixed_init()

Definition at line 139 of file ascon-prf.c.

◆ ascon_prf_free()

void ascon_prf_free ( ascon_prf_state_t * state )

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

Parameters

state PRF state to be freed.

Definition at line 146 of file ascon-prf.c.

◆ ascon_prf_init()

void ascon_prf_init	(	ascon_prf_state_t *	state,
		const unsigned char *	key
	)

Initializes the state for an incremental ASCON-Prf operation.

Parameters

state	PRF state to be initialized.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

This function will set ASCON-Prf into unlimited output mode.

See also: ascon_prf_fixed_init(), ascon_prf_absorb(), ascon_prf_squeeze()

Definition at line 110 of file ascon-prf.c.

◆ ascon_prf_reinit()

void ascon_prf_reinit	(	ascon_prf_state_t *	state,
		const unsigned char *	key
	)

Re-initializes the state for an incremental ASCON-Prf operation.

Parameters

state	PRF state to be re-initialized.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

This function is equivalent to calling ascon_prf_free() and then ascon_prf_init() to restart the hashing process.

See also: ascon_prf_fixed_reinit(), ascon_prf_init()

Definition at line 133 of file ascon-prf.c.

◆ ascon_prf_short()

int ascon_prf_short	(	unsigned char *	out,
		size_t	outlen,
		const unsigned char *	in,
		size_t	inlen,
		const unsigned char *	key
	)

Processes a key and input data with ASCON-PrfShort to produce a tag.

Parameters

out	Buffer to receive the PRF tag which must be at least outlen bytes in length.
outlen	Length of the output buffer in bytes between 0 and ASCON_PRF_SHORT_MAX_OUTPUT_SIZE.
in	Points to the input data to be processed.
inlen	Length of the input data in bytes between 0 and ASCON_PRF_SHORT_MAX_INPUT_SIZE.
key	Points to the ASCON_PRF_KEY_SIZE bytes of the key.

Returns: 0 if the output was generated, or -1 if either outlen or inlen are out of range.

See also: ascon_prf(), ascon_prf_fixed(), ascon_mac()

Definition at line 62 of file ascon-prf.c.

◆ ascon_prf_squeeze()

void ascon_prf_squeeze	(	ascon_prf_state_t *	state,
		unsigned char *	out,
		size_t	outlen
	)

Squeezes output from an incremental ASCON-Prf operation.

Parameters

state	PRF state to squeeze output from.
out	Points to the output buffer to receive the output.
outlen	Number of bytes of output that are required for this call.

This function can be called any number of times until all desired output has been retrieved.

See also: ascon_prf_init(), ascon_prf_absorb()

Definition at line 207 of file ascon-prf.c.

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ASCON_MAC_KEY_SIZE

◆ ASCON_MAC_TAG_SIZE

◆ ASCON_PRF_KEY_SIZE

◆ ASCON_PRF_SHORT_KEY_SIZE

◆ ASCON_PRF_SHORT_MAX_INPUT_SIZE

◆ ASCON_PRF_SHORT_MAX_OUTPUT_SIZE

◆ ASCON_PRF_SHORT_TAG_SIZE

◆ ASCON_PRF_TAG_SIZE

Function Documentation

◆ ascon_mac()

◆ ascon_mac_verify()

◆ ascon_prf()

◆ ascon_prf_absorb()

◆ ascon_prf_fixed()

◆ ascon_prf_fixed_init()

◆ ascon_prf_fixed_reinit()

◆ ascon_prf_free()

◆ ascon_prf_init()

◆ ascon_prf_reinit()

◆ ascon_prf_short()

◆ ascon_prf_squeeze()