Direct access to the ASCON permutation primitive. More...

#include <stdint.h>
#include <stddef.h>

Classes
union	ascon_state_t
	Structure of the internal state of the ASCON permutation. More...

Macros
#define	ascon_permute12(state) ascon_permute((state), 0)
	Permutes the ASCON state with 12 rounds of the permutation. More...

#define	ascon_permute8(state) ascon_permute((state), 4)
	Permutes the ASCON state with 8 rounds of the permutation. More...

#define	ascon_permute6(state) ascon_permute((state), 6)
	Permutes the ASCON state with 6 rounds of the permutation. More...

Functions
void	ascon_init (ascon_state_t *state)
	Initializes the words of the ASCON permutation state to zero. More...

void	ascon_free (ascon_state_t *state)
	Frees an ASCON permutation state and attempts to destroy any sensitive material. More...

void	ascon_add_bytes (ascon_state_t state, const uint8_t data, unsigned offset, unsigned size)
	Adds bytes to the ASCON state by XOR'ing them with existing bytes. More...

void	ascon_overwrite_bytes (ascon_state_t state, const uint8_t data, unsigned offset, unsigned size)
	Overwrites existing bytes in the ASCON state. More...

void	ascon_overwrite_with_zeroes (ascon_state_t *state, unsigned offset, unsigned size)
	Overwrites a part of the ASCON state with zeroes. More...

void	ascon_extract_bytes (const ascon_state_t state, uint8_t data, unsigned offset, unsigned size)
	Extracts bytes from the ASCON state. More...

void	ascon_extract_and_add_bytes (const ascon_state_t state, const uint8_t input, uint8_t *output, unsigned offset, unsigned size)
	Extracts bytes from the ASCON state and XOR's them with input bytes to produce output bytes. More...

void	ascon_extract_and_overwrite_bytes (ascon_state_t state, const uint8_t input, uint8_t *output, unsigned offset, unsigned size)
	Extracts bytes from the ASCON state and XOR's them with input bytes to produce output bytes. Also write the original input bytes into the ASCON state. More...

void	ascon_permute (ascon_state_t *state, uint8_t first_round)
	Permutes the ASCON state with a specified number of rounds. More...

void	ascon_release (ascon_state_t *state)
	Temporarily releases access to any shared hardware resources that a permutation state was using. More...

void	ascon_acquire (ascon_state_t *state)
	Re-acquires access to any shared hardware resources that a permutation state was using. More...

void	ascon_copy (ascon_state_t dest, const ascon_state_t src)
	Copies the entire ASCON permutation state from a source to a destination. More...

Detailed Description

Direct access to the ASCON permutation primitive.

Normally applications do not need to use the definitions in this file directly. They would instead use other functions to access AEAD and hashing modes. However, if the application needs to implement its own mode, then these definitions can help with that.

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

Definition in file permutation.h.

Macro Definition Documentation

◆ ascon_permute12

#define ascon_permute12 ( state ) ascon_permute((state), 0)

Permutes the ASCON state with 12 rounds of the permutation.

Parameters

state The ASCON state in "operational" form.

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 199 of file permutation.h.

◆ ascon_permute6

#define ascon_permute6 ( state ) ascon_permute((state), 6)

Permutes the ASCON state with 6 rounds of the permutation.

Parameters

state The ASCON state in "operational" form.

Definition at line 213 of file permutation.h.

◆ ascon_permute8

#define ascon_permute8 ( state ) ascon_permute((state), 4)

Permutes the ASCON state with 8 rounds of the permutation.

Parameters

state The ASCON state in "operational" form.

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 206 of file permutation.h.

Function Documentation

◆ ascon_acquire()

void ascon_acquire ( ascon_state_t * state )

Re-acquires access to any shared hardware resources that a permutation state was using.

Parameters

state The ASCON state to be re-acquired.

See also: ascon_release()

Definition at line 267 of file ascon-sliced32.c.

◆ ascon_add_bytes()

void ascon_add_bytes	(	ascon_state_t *	state,
		const uint8_t *	data,
		unsigned	offset,
		unsigned	size
	)

Adds bytes to the ASCON state by XOR'ing them with existing bytes.

Parameters

state	The ASCON state in "operational" form.
data	Points to the data to add to the state.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to add to the state between 0 and 40.

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

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

◆ ascon_copy()

void ascon_copy	(	ascon_state_t *	dest,
		const ascon_state_t *	src
	)

Copies the entire ASCON permutation state from a source to a destination.

Parameters

dest	The destination to copy to.
src	The source to copy from.

The destination must be acquired and the source must be released.

Definition at line 273 of file ascon-sliced32.c.

◆ ascon_extract_and_add_bytes()

void ascon_extract_and_add_bytes	(	const ascon_state_t *	state,
		const uint8_t *	input,
		uint8_t *	output,
		unsigned	offset,
		unsigned	size
	)

Extracts bytes from the ASCON state and XOR's them with input bytes to produce output bytes.

Parameters

state	The ASCON state in "operational" form.
input	Points to the input buffer.
output	Points to the output buffer.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to extract from the state between 0 and 40.

Definition at line 182 of file ascon-sliced32.c.

◆ ascon_extract_and_overwrite_bytes()

void ascon_extract_and_overwrite_bytes	(	ascon_state_t *	state,
		const uint8_t *	input,
		uint8_t *	output,
		unsigned	offset,
		unsigned	size
	)

Extracts bytes from the ASCON state and XOR's them with input bytes to produce output bytes. Also write the original input bytes into the ASCON state.

Parameters

state	The ASCON state in "operational" form.
input	Points to the input buffer.
output	Points to the output buffer.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to extract from the state between 0 and 40.

This function has the effect of calling ascon_extract_and_add_bytes() and then ascon_overwrite_bytes(), but it also works for the case where input and output are the same buffer. This combination is typically used for AEAD decryption where the input ciphertext needs to be incorporated into the state to authenticate it.

Examples: permutation/encrypt/main.c.

Definition at line 217 of file ascon-sliced32.c.

◆ ascon_extract_bytes()

void ascon_extract_bytes	(	const ascon_state_t *	state,
		uint8_t *	data,
		unsigned	offset,
		unsigned	size
	)

Extracts bytes from the ASCON state.

Parameters

state	The ASCON state in "operational" form.
data	Points to the buffer to receive the extracted bytes.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to extract from the state between 0 and 40.

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 150 of file ascon-sliced32.c.

◆ ascon_free()

void ascon_free ( ascon_state_t * state )

Frees an ASCON permutation state and attempts to destroy any sensitive material.

Parameters

state The ASCON state to be freed.

If ascon_init() had to allocate internal structures to interface with a platform-specific acceleration module, then this function will deallocate those structures.

There is no guarantee that all traces of the sensitive material will be gone. Fragments may be left on the stack or in registers from previous permutation calls. This function will make a best effort given the constraints of the platform.

See also: ascon_init()

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 42 of file ascon-sliced32.c.

◆ ascon_init()

void ascon_init ( ascon_state_t * state )

Initializes the words of the ASCON permutation state to zero.

Parameters

state The ASCON state to initialize.

This function might allocate internal state to hold more information than will fit in the ascon_state_t structure to interface with a platform-specific acceleration module.

It is always a good idea to call this before using the permutation state. Also make sure to call ascon_free() when the permutation state is no longer required to deallocate the internal state.

See also: ascon_free()

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 32 of file ascon-sliced32.c.

◆ ascon_overwrite_bytes()

void ascon_overwrite_bytes	(	ascon_state_t *	state,
		const uint8_t *	data,
		unsigned	offset,
		unsigned	size
	)

Overwrites existing bytes in the ASCON state.

Parameters

state	The ASCON state in "operational" form.
data	Points to the data to write to the state.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to overwrite between 0 and 40.

Examples: permutation/encrypt/main.c, and permutation/hash/main.c.

Definition at line 84 of file ascon-sliced32.c.

◆ ascon_overwrite_with_zeroes()

void ascon_overwrite_with_zeroes	(	ascon_state_t *	state,
		unsigned	offset,
		unsigned	size
	)

Overwrites a part of the ASCON state with zeroes.

Parameters

state	The ASCON state in "operational" form.
offset	Offset into the state between 0 and 40 - size.
size	Number of bytes to overwrite between 0 and 40.

Definition at line 121 of file ascon-sliced32.c.

◆ ascon_permute()

void ascon_permute	(	ascon_state_t *	state,
		uint8_t	first_round
	)

Permutes the ASCON state with a specified number of rounds.

Parameters

state	The ASCON state in "operational" form.
first_round	The first round to execute, between 0 and 11. The number of rounds will be 12 - first_round.

Definition at line 36 of file ascon-c32.c.

◆ ascon_release()

void ascon_release ( ascon_state_t * state )

Temporarily releases access to any shared hardware resources that a permutation state was using.

Parameters

state The ASCON state to be released.

Operation on the state will resume the next time ascon_acquire() is called.

The ascon_free() function implicitly releases the state so it usually isn't necessary to release the state explicitly. However, if the application will not be using the state for some time then it should call ascon_release() to allow other tasks on the system to access the shared hardware.

See also: ascon_acquire()

Definition at line 261 of file ascon-sliced32.c.

Classes

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ascon_permute12

◆ ascon_permute6

◆ ascon_permute8

Function Documentation

◆ ascon_acquire()

◆ ascon_add_bytes()

◆ ascon_copy()

◆ ascon_extract_and_add_bytes()

◆ ascon_extract_and_overwrite_bytes()

◆ ascon_extract_bytes()

◆ ascon_free()

◆ ascon_init()

◆ ascon_overwrite_bytes()

◆ ascon_overwrite_with_zeroes()

◆ ascon_permute()

◆ ascon_release()