API for raw access to the ASCON permutation. More...

#include <stdint.h>

Data Structures
union	ascon_permutation_state_t
	Structure of the internal state of the ASCON permutation. More...

Macros
#define	ASCON_STATE_SIZE 40
	Size of the ASCON permutation state in bytes.

#define	ASCON_MAX_ROUNDS 12
	Maximum number of rounds for the ASCON permutation.

Functions
void	ascon_init (ascon_permutation_state_t *state)
	Initializes an ASCON state to all-zeroes. More...

void	ascon_from_operational (ascon_permutation_state_t *state)
	Converts an ASCON state from operational mode to traditional mode. More...

void	ascon_to_operational (ascon_permutation_state_t *state)
	Converts an ASCON state from traditional mode to operational mode. More...

void	ascon_add_byte (ascon_permutation_state_t *state, unsigned char data, unsigned offset)
	Adds a single byte to the state by XOR'ing it with the existing byte. More...

void	ascon_add_bytes (ascon_permutation_state_t state, const unsigned char data, unsigned offset, unsigned length)
	Adds bytes to the state by XOR'ing them with the existing bytes. More...

void	ascon_overwrite_bytes (ascon_permutation_state_t state, const unsigned char data, unsigned offset, unsigned length)
	Writes bytes to the state, overwriting any existing bytes. More...

void	ascon_overwrite_with_zeroes (ascon_permutation_state_t *state, unsigned count)
	Overwrites the leading part of the state with zeroes. More...

void	ascon_permute_n_rounds (ascon_permutation_state_t *state, unsigned rounds)
	Performs N rounds of the ASCON permutation. More...

void	ascon_permute_all_rounds (ascon_permutation_state_t *state)
	Performs all 12 rounds of the ASCON permutation. More...

void	ascon_extract_bytes (const ascon_permutation_state_t state, unsigned char data, unsigned offset, unsigned length)
	Extracts bytes from an ASCON state. More...

void	ascon_extract_and_add_bytes (const ascon_permutation_state_t state, const unsigned char input, unsigned char *output, unsigned offset, unsigned length)
	Extracts bytes from an ASCON state and XOR's them with input data. More...

void	ascon_encrypt_bytes (ascon_permutation_state_t state, const unsigned char input, unsigned char *output, unsigned offset, unsigned length, int padded)
	Encrypts bytes by XOR'ing them with the state and then adding the encrypted version back to the state. More...

void	ascon_decrypt_bytes (ascon_permutation_state_t state, const unsigned char input, unsigned char *output, unsigned offset, unsigned length, int padded)
	Decrypts bytes by XOR'ing them with the state and then overwriting the state with the original ciphertext. More...

Detailed Description

API for raw access to the ASCON permutation.

This API implements the SnP "state and permutation" representation for the ASCON state. Functions are provided for adding input data to the state, performing permutations, and extracting output data.

The ASCON state has two modes: "traditional" and "operational". In the traditional mode, the bytes are laid out in the standard big-endian order. In the "operational" mode, the bytes may be laid out in a different platform-dependent order for greater efficiency.

Most functions expect the state to be in operational mode. The application can call ascon_from_operational() to convert to the traditional order so that it can more easily extract data from the state directly.

The application can also populate data into the state in the traditional order and call ascon_to_operational() to convert it into operational mode for other functions. This may be useful when initializing the state with a starting arrangement of keys, nonces, and initialization vector values.

References: http://competitions.cr.yp.to/round3/asconv12.pdf, http://ascon.iaik.tugraz.at/

Function Documentation

void ascon_add_byte	(	ascon_permutation_state_t *	state,
		unsigned char	data,
		unsigned	offset
	)

Adds a single byte to the state by XOR'ing it with the existing byte.

Parameters

state	The state to add the bytes to.
data	The data byte to add to the state.
offset	The offset into the state for adding the byte, between 0 and ASCON_STATE_SIZE - 1.

If offset is out of range, the function call will be ignored.

The state is assumed to be in the "operational" mode.

See Also: ascon_add_bytes()

void ascon_add_bytes	(	ascon_permutation_state_t *	state,
		const unsigned char *	data,
		unsigned	offset,
		unsigned	length
	)

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

Parameters

state	The state to add the bytes to.
data	Points to the bytes to be added to the state.
offset	The offset into the state for adding the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to add to the state, between 0 and ASCON_STATE_SIZE - offset.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_add_byte(), ascon_extract_bytes(), ascon_overwrite_bytes()

void ascon_decrypt_bytes	(	ascon_permutation_state_t *	state,
		const unsigned char *	input,
		unsigned char *	output,
		unsigned	offset,
		unsigned	length,
		int	padded
	)

Decrypts bytes by XOR'ing them with the state and then overwriting the state with the original ciphertext.

Parameters

state	The state to use to encrypt the bytes.
input	Points to the buffer that contains the input ciphertext data to be encrypted.
output	Points to the buffer to receive the plaintext data.
offset	The offset into the state for extracting the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to extract from the state, between 0 and ASCON_STATE_SIZE - offset.
padded	Non-zero to pad the input data with a 0x80 byte.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored. For each byte, this function computes:

output[i] = input[i] ^ state[i + offset]

state[i + offset] = input[i]

This function is useful when implementing AEAD modes with ASCON where the ciphertext needs to be re-absorbed into the state for authentication purposes.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_encrypt_bytes(), ascon_extract_and_add_bytes()

void ascon_encrypt_bytes	(	ascon_permutation_state_t *	state,
		const unsigned char *	input,
		unsigned char *	output,
		unsigned	offset,
		unsigned	length,
		int	padded
	)

Encrypts bytes by XOR'ing them with the state and then adding the encrypted version back to the state.

Parameters

state	The state to use to encrypt the bytes.
input	Points to the buffer that contains the input plaintext data to be encrypted.
output	Points to the buffer to receive the ciphertext data.
offset	The offset into the state for extracting the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to extract from the state, between 0 and ASCON_STATE_SIZE - offset.
padded	Non-zero to pad the input data with a 0x80 byte.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored. For each byte, this function computes:

output[i] = input[i] ^ state[i + offset]

state[i + offset] = output[i]

This function is useful when implementing AEAD modes with ASCON where the ciphertext needs to be re-absorbed into the state for authentication purposes.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_decrypt_bytes(), ascon_extract_and_add_bytes()

void ascon_extract_and_add_bytes	(	const ascon_permutation_state_t *	state,
		const unsigned char *	input,
		unsigned char *	output,
		unsigned	offset,
		unsigned	length
	)

Extracts bytes from an ASCON state and XOR's them with input data.

Parameters

state	The state to extract the bytes from.
input	Points to the buffer that contains the input data to XOR the extracted bytes against.
output	Points to the buffer to receive the final data.
offset	The offset into the state for extracting the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to extract from the state, between 0 and ASCON_STATE_SIZE - offset.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored. For each byte, this function computes:

output[i] = input[i] ^ state[i + offset]

If your intention is to encrypt plaintext data and then re-absorb the ciphertext into the state for authentication, then ascon_encrypt_bytes() is a better option than this function.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_add_bytes(), ascon_extract_bytes(), ascon_encrypt_bytes()

void ascon_extract_bytes	(	const ascon_permutation_state_t *	state,
		unsigned char *	data,
		unsigned	offset,
		unsigned	length
	)

Extracts bytes from an ASCON state.

Parameters

state	The state to extract the bytes from.
data	Points to the buffer to receive the extracted bytes.
offset	The offset into the state for extracting the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to extract from the state, between 0 and ASCON_STATE_SIZE - offset.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_add_bytes(), ascon_extract_and_add_bytes()

void ascon_from_operational ( ascon_permutation_state_t * state )

Converts an ASCON state from operational mode to traditional mode.

Parameters

state The state to be converted.

See Also: ascon_to_operational()

void ascon_init ( ascon_permutation_state_t * state )

Initializes an ASCON state to all-zeroes.

Parameters

state The state to be initialized.

On exit, the state will be in the "operational" mode.

void ascon_overwrite_bytes	(	ascon_permutation_state_t *	state,
		const unsigned char *	data,
		unsigned	offset,
		unsigned	length
	)

Writes bytes to the state, overwriting any existing bytes.

Parameters

state	The state to write the bytes to.
data	Points to the bytes to be written to the state.
offset	The offset into the state for writing the bytes, between 0 and ASCON_STATE_SIZE - 1.
length	The number of bytes to write to the state, between 0 and ASCON_STATE_SIZE - offset.

If offset is out of range, the function call will be ignored. If offset + length would extend beyond the end of the state, then extra bytes will be ignored.

The state is assumed to be in the "operational" mode. Best performance is achieved when offset and length are multiples of 8.

See Also: ascon_add_bytes(), ascon_overwrite_with_zeroes()

void ascon_overwrite_with_zeroes	(	ascon_permutation_state_t *	state,
		unsigned	count
	)

Overwrites the leading part of the state with zeroes.

Parameters

state	The state to overwrite.
count	The number of bytes to overwrite, between 0 and ASCON_STATE_SIZE.

If count is greater than or equal to ASCON_STATE_SIZE, then this function is equivalent to calling ascon_init().

The state is assumed to be in the "operational" mode. Best performance is achieved when count is a multiple of 8.

See Also: ascon_overwrite_bytes(), ascon_add_bytes()

void ascon_permute_all_rounds ( ascon_permutation_state_t * state )

Performs all 12 rounds of the ASCON permutation.

Parameters

state The state to be permuted.

The state is assumed to be in the "operational" mode.

See Also: ascon_permute_n_rounds()

void ascon_permute_n_rounds	(	ascon_permutation_state_t *	state,
		unsigned	rounds
	)

Performs N rounds of the ASCON permutation.

Parameters

state	The state to be permuted.
rounds	The number of rounds to be performed between 0 and ASCON_MAX_ROUNDS.

If rounds is greater than ASCON_MAX_ROUNDS, then it will be clamped to that value.

The state is assumed to be in the "operational" mode.

See Also: ascon_permute_all_rounds()

void ascon_to_operational ( ascon_permutation_state_t * state )

Converts an ASCON state from traditional mode to operational mode.

Parameters

state The state to be converted.

See Also: ascon_from_operational()

Data Structures

Macros

Functions

Detailed Description

Function Documentation