Ascon cipher - Lightweight Authenticated Encryption & Hashing, also with Init-Update-Final paradigm. More...

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

Include dependency graph for ascon.h:

Data Structures
struct	ascon_sponge
	Internal cipher sponge state (320 bits). More...

struct	ascon_bufstate
	Internal cipher sponge state associated with a buffer holding for less-than-rate updates. More...

struct	ascon_aead_ctx
	Cipher context for authenticated encryption and validated decryption. More...

Macros
#define	ASCON_INPUT_ASSERTS 1
	When defined, enables the runtime assertions on the parameters of all functions of the library API using ASCON_ASSERT. More...

#define	ASCON_ASSERT(expr) assert(expr)
	Assertion macro, used to stop execution when a critical error is encountered. More...

#define	ASCON_WINDOWS 1
	Indicator simplifying the check for the Windows platform (undefined on other platforms). More...

#define	ASCON_API __declspec(dllexport)
	Marker of all the library's public API functions. More...

#define	ASCON_API_VERSION_MAJOR 1
	Major version of this API conforming to semantic versioning. More...

#define	ASCON_API_VERSION_MINOR 2
	Minor version of this API conforming to semantic versioning. More...

#define	ASCON_API_VERSION_BUGFIX 1
	Bugfix/patch version of this API conforming to semantic versioning. More...

#define	ASCON_API_VERSION "1.2.1"
	Version of this API conforming to semantic versioning as a string. More...

#define	ASCON_AEAD128_KEY_LEN 16U
	Length in bytes of the secret symmetric key used for the Ascon128 cipher. More...

#define	ASCON_AEAD128a_KEY_LEN 16U
	Length in bytes of the secret symmetric key used for the Ascon128a cipher. More...

#define	ASCON_AEAD80pq_KEY_LEN 20U
	Length in bytes of the secret symmetric key used for the Ascon80pq cipher. More...

#define	ASCON_AEAD_NONCE_LEN 16U
	Length in bytes of the public nonce used for authenticated encryption and decryption. More...

#define	ASCON_AEAD_TAG_MIN_SECURE_LEN 16U
	Minimum recommended length in bytes of the authentication tag generated by the authenticated encryption and validated by the decryption. More...

#define	ASCON_HASH_DIGEST_LEN 32U
	Length in bytes of the digest generated by the fixed-size (non-xof) hash function. More...

#define	ASCON_HASHA_DIGEST_LEN ASCON_HASH_DIGEST_LEN
	Length in bytes of the digest generated by the fixed-size (non-xof) hasha function. More...

#define	ASCON_RATE 8U
	Number of bytes the cipher can process at the time in AEAD128 mode and hashing. More...

#define	ASCON_DOUBLE_RATE (2U * ASCON_RATE)
	Number of bytes the cipher can process at the time in AEAD128a mode. More...

#define	ASCON_TAG_OK true
	The tag is valid thus the associated data and ciphertext were intact. More...

#define	ASCON_TAG_INVALID false
	The tag is invalid thus the associated data and decrypted data should be ignored. More...

Typedefs
typedef struct ascon_sponge	ascon_sponge_t
	Internal cipher sponge state (320 bits). More...

typedef struct ascon_bufstate	ascon_bufstate_t
	Internal cipher sponge state associated with a buffer holding for less-than-rate updates. More...

typedef ascon_bufstate_t	ascon_hash_ctx_t
	Cipher context for hashing. More...

typedef struct ascon_aead_ctx	ascon_aead_ctx_t
	Cipher context for authenticated encryption and validated decryption. More...

Functions
ASCON_API void	ascon_aead128_encrypt (uint8_t ciphertext, uint8_t tag, const uint8_t key[ASCON_AEAD128_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t plaintext, size_t assoc_data_len, size_t plaintext_len, size_t tag_len)
	Offline symmetric encryption using Ascon128. More...

ASCON_API void	ascon_aead128_init (ascon_aead_ctx_t *ctx, const uint8_t key[ASCON_AEAD128_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN])
	Online symmetric encryption/decryption using Ascon128, initialisation. More...

ASCON_API void	ascon_aead128_assoc_data_update (ascon_aead_ctx_t ctx, const uint8_t assoc_data, size_t assoc_data_len)
	Online symmetric encryption/decryption using Ascon128, feeding associated data. More...

ASCON_API size_t	ascon_aead128_encrypt_update (ascon_aead_ctx_t ctx, uint8_t ciphertext, const uint8_t *plaintext, size_t plaintext_len)
	Online symmetric encryption using Ascon128, feeding plaintext and getting ciphertext. More...

ASCON_API size_t	ascon_aead128_encrypt_final (ascon_aead_ctx_t ctx, uint8_t ciphertext, uint8_t *tag, size_t tag_len)
	Online symmetric encryption using Ascon128, finalisation and tag generation. More...

ASCON_API bool	ascon_aead128_decrypt (uint8_t plaintext, const uint8_t key[ASCON_AEAD128_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t ciphertext, const uint8_t expected_tag, size_t assoc_data_len, size_t ciphertext_len, size_t expected_tag_len)
	Offline symmetric decryption using Ascon128. More...

ASCON_API size_t	ascon_aead128_decrypt_update (ascon_aead_ctx_t ctx, uint8_t plaintext, const uint8_t *ciphertext, size_t ciphertext_len)
	Online symmetric decryption using Ascon128, feeding ciphertext and getting plaintext. More...

ASCON_API size_t	ascon_aead128_decrypt_final (ascon_aead_ctx_t ctx, uint8_t plaintext, bool is_tag_valid, const uint8_t expected_tag, size_t expected_tag_len)
	Online symmetric decryption using Ascon128, finalisation and tag validation. More...

ASCON_API void	ascon_aead_cleanup (ascon_aead_ctx_t *ctx)
	Security cleanup of the AEAD context, in case the online processing is not completed to the end. More...

ASCON_API void	ascon_aead128a_encrypt (uint8_t ciphertext, uint8_t tag, const uint8_t key[ASCON_AEAD128_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t plaintext, size_t assoc_data_len, size_t plaintext_len, size_t tag_len)
	Offline symmetric encryption using Ascon128a, which uses a double data rate compared to Ascon128. More...

ASCON_API void	ascon_aead128a_init (ascon_aead_ctx_t *ctx, const uint8_t key[ASCON_AEAD128a_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN])
	Online symmetric encryption/decryption using Ascon128a, initialisation. More...

ASCON_API void	ascon_aead128a_assoc_data_update (ascon_aead_ctx_t ctx, const uint8_t assoc_data, size_t assoc_data_len)
	Online symmetric encryption/decryption using Ascon128a, feeding associated data. More...

ASCON_API size_t	ascon_aead128a_encrypt_update (ascon_aead_ctx_t ctx, uint8_t ciphertext, const uint8_t *plaintext, size_t plaintext_len)
	Online symmetric encryption using Ascon128a, feeding plaintext and getting ciphertext. More...

ASCON_API size_t	ascon_aead128a_encrypt_final (ascon_aead_ctx_t ctx, uint8_t ciphertext, uint8_t *tag, size_t tag_len)
	Online symmetric encryption using Ascon128a, finalisation and tag generation. More...

ASCON_API bool	ascon_aead128a_decrypt (uint8_t plaintext, const uint8_t key[ASCON_AEAD128a_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t ciphertext, const uint8_t expected_tag, size_t assoc_data_len, size_t ciphertext_len, size_t expected_tag_len)
	Offline symmetric decryption using Ascon128a, which uses a double data rate compared to Ascon128. More...

ASCON_API size_t	ascon_aead128a_decrypt_update (ascon_aead_ctx_t ctx, uint8_t plaintext, const uint8_t *ciphertext, size_t ciphertext_len)
	Online symmetric decryption using Ascon128a, feeding ciphertext and getting plaintext. More...

ASCON_API size_t	ascon_aead128a_decrypt_final (ascon_aead_ctx_t ctx, uint8_t plaintext, bool is_tag_valid, const uint8_t expected_tag, size_t expected_tag_len)
	Online symmetric decryption using Ascon128a, finalisation and tag validation. More...

ASCON_API void	ascon_aead80pq_encrypt (uint8_t ciphertext, uint8_t tag, const uint8_t key[ASCON_AEAD80pq_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t plaintext, size_t assoc_data_len, size_t plaintext_len, size_t tag_len)
	Offline symmetric encryption using Ascon80pq, which uses a larger key. More...

ASCON_API void	ascon_aead80pq_init (ascon_aead_ctx_t *ctx, const uint8_t key[ASCON_AEAD80pq_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN])
	Online symmetric encryption/decryption using Ascon80pq, initialisation - note that a larger key is used compared to Ascon128 and Ascon128a. More...

ASCON_API void	ascon_aead80pq_assoc_data_update (ascon_aead_ctx_t ctx, const uint8_t assoc_data, size_t assoc_data_len)
	Online symmetric encryption/decryption using Ascon80pq, feeding associated data. More...

ASCON_API size_t	ascon_aead80pq_encrypt_update (ascon_aead_ctx_t ctx, uint8_t ciphertext, const uint8_t *plaintext, size_t plaintext_len)
	Online symmetric encryption using Ascon80pq, feeding plaintext and getting ciphertext. More...

ASCON_API size_t	ascon_aead80pq_encrypt_final (ascon_aead_ctx_t ctx, uint8_t ciphertext, uint8_t *tag, size_t tag_len)
	Online symmetric encryption using Ascon80pq, finalisation and tag generation. More...

ASCON_API bool	ascon_aead80pq_decrypt (uint8_t plaintext, const uint8_t key[ASCON_AEAD80pq_KEY_LEN], const uint8_t nonce[ASCON_AEAD_NONCE_LEN], const uint8_t assoc_data, const uint8_t ciphertext, const uint8_t expected_tag, size_t assoc_data_len, size_t ciphertext_len, size_t expected_tag_len)
	Offline symmetric decryption using Ascon80pq, which uses a larger key compared to Ascon128. More...

ASCON_API size_t	ascon_aead80pq_decrypt_update (ascon_aead_ctx_t ctx, uint8_t plaintext, const uint8_t *ciphertext, size_t ciphertext_len)
	Online symmetric decryption using Ascon80pq, feeding ciphertext and getting plaintext. More...

ASCON_API size_t	ascon_aead80pq_decrypt_final (ascon_aead_ctx_t ctx, uint8_t plaintext, bool is_tag_valid, const uint8_t expected_tag, size_t expected_tag_len)
	Online symmetric decryption using Ascon80pq, finalisation and tag validation. More...

ASCON_API void	ascon_hash (uint8_t digest[ASCON_HASH_DIGEST_LEN], const uint8_t *data, size_t data_len)
	Offline Ascon-Hash with fixed digest length. More...

ASCON_API void	ascon_hasha (uint8_t digest[ASCON_HASHA_DIGEST_LEN], const uint8_t *data, size_t data_len)
	Offline Ascon-Hasha with fixed digest length. More...

ASCON_API bool	ascon_hash_matches (const uint8_t expected_digest[ASCON_HASH_DIGEST_LEN], const uint8_t *data, size_t data_len)
	Offline Ascon-Hash with fixed digest length, finalisation and digest validation of the expected one. More...

ASCON_API bool	ascon_hasha_matches (const uint8_t expected_digest[ASCON_HASHA_DIGEST_LEN], const uint8_t *data, size_t data_len)
	Offline Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one. More...

ASCON_API void	ascon_hash_init (ascon_hash_ctx_t *ctx)
	Online Ascon-Hash with fixed digest length, initialisation. More...

ASCON_API void	ascon_hasha_init (ascon_hash_ctx_t *ctx)
	Online Ascon-Hasha with fixed digest length, initialisation. More...

ASCON_API void	ascon_hash_update (ascon_hash_ctx_t ctx, const uint8_t data, size_t data_len)
	Online Ascon-Hash with fixed digest length, feeding data to hash. More...

ASCON_API void	ascon_hasha_update (ascon_hash_ctx_t ctx, const uint8_t data, size_t data_len)
	Online Ascon-Hasha with fixed digest length, feeding data to hash. More...

ASCON_API void	ascon_hash_final (ascon_hash_ctx_t *ctx, uint8_t digest[ASCON_HASH_DIGEST_LEN])
	Online Ascon-Hash with fixed digest length, finalisation and digest generation. More...

ASCON_API void	ascon_hasha_final (ascon_hash_ctx_t *ctx, uint8_t digest[ASCON_HASHA_DIGEST_LEN])
	Online Ascon-Hasha with fixed digest length, finalisation and digest generation. More...

ASCON_API bool	ascon_hash_final_matches (ascon_hash_ctx_t *ctx, const uint8_t expected_digest[ASCON_HASH_DIGEST_LEN])
	Online Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one. More...

ASCON_API bool	ascon_hasha_final_matches (ascon_hash_ctx_t *ctx, const uint8_t expected_digest[ASCON_HASHA_DIGEST_LEN])
	Online Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one. More...

ASCON_API void	ascon_hash_xof (uint8_t digest, const uint8_t data, size_t digest_len, size_t data_len)
	Offline Ascon-Hash with custom digest length (eXtendable Output Function, XOF). More...

ASCON_API void	ascon_hasha_xof (uint8_t digest, const uint8_t data, size_t digest_len, size_t data_len)
	Offline Ascon-Hasha with custom digest length (eXtendable Output Function, XOF). More...

ASCON_API bool	ascon_hash_xof_matches (const uint8_t expected_digest, const uint8_t data, size_t expected_digest_len, size_t data_len)
	Offline Ascon-Hash with custom digest length (eXtendable Output Function, XOF) and validation of the expected one. More...

ASCON_API bool	ascon_hasha_xof_matches (const uint8_t expected_digest, const uint8_t data, size_t expected_digest_len, size_t data_len)
	Offline Ascon-Hasha with custom digest length (eXtendable Output Function, XOF) and validation of the expected one. More...

ASCON_API void	ascon_hash_xof_init (ascon_hash_ctx_t *ctx)
	Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), initialisation. More...

ASCON_API void	ascon_hasha_xof_init (ascon_hash_ctx_t *ctx)
	Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), initialisation. More...

ASCON_API void	ascon_hash_xof_update (ascon_hash_ctx_t ctx, const uint8_t data, size_t data_len)
	Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), feeding data to hash. More...

ASCON_API void	ascon_hasha_xof_update (ascon_hash_ctx_t ctx, const uint8_t data, size_t data_len)
	Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), feeding data to hash. More...

ASCON_API void	ascon_hash_xof_final (ascon_hash_ctx_t ctx, uint8_t digest, size_t digest_len)
	Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), finalisation and digest generation. More...

ASCON_API void	ascon_hasha_xof_final (ascon_hash_ctx_t ctx, uint8_t digest, size_t digest_len)
	Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), finalisation and digest generation. More...

ASCON_API bool	ascon_hash_xof_final_matches (ascon_hash_ctx_t ctx, const uint8_t expected_digest, size_t expected_digest_len)
	Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), finalisation and digest validation of the expected one. More...

ASCON_API bool	ascon_hasha_xof_final_matches (ascon_hash_ctx_t ctx, const uint8_t expected_digest, size_t expected_digest_len)
	Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), finalisation and digest validation of the expected one. More...

ASCON_API void	ascon_hash_cleanup (ascon_hash_ctx_t *ctx)
	Security cleanup of the hashing context, in case the online processing is not completed to the end. More...

Detailed Description

Ascon cipher - Lightweight Authenticated Encryption & Hashing, also with Init-Update-Final paradigm.

Ascon is a family of authenticated encryption and hashing algorithms designed to be lightweight and easy to implement, even with added countermeasures against side-channel attacks.

For more information on the Ascon cipher itself, visit https://ascon.iaik.tugraz.at/

This file is the interface to the Ascon library providing:

the Ascon symmetric AEAD ciphers Ascon128, Ascon128a, Ascon80pq
the Ascon fixed-size output hash and variable-size output hash (XOF)

All functionalities are available in:

online form (init-update-final paradigm): the data is processed one chunk at the time; useful if it's still being received or does not fit into memory
offline form: the data is available as a whole in memory and processed in one go

Library dependencies:

only the C99 or C11 standard library, as seen in the #include statements of this file

License: Creative Commons Zero (CC0) 1.0

Authors: See AUTHORS.md file

Macro Definition Documentation

◆ ASCON_INPUT_ASSERTS

#define ASCON_INPUT_ASSERTS 1

When defined, enables the runtime assertions on the parameters of all functions of the library API using ASCON_ASSERT.

The check is mostly against NULL pointers, for the correct order of calling of the many Init-Update-Final functions and against mixing functions from different AEAD algorithms (128 vs 128a vs 80pq). It's recommended to use it in debug mode, optionally also in release mode.

If ASCON_INPUT_ASSERTS is defined, the user can also pre-define ASCON_ASSERT to any custom assertion macro or function.

See also: ASCON_ASSERT

◆ ASCON_ASSERT

#define ASCON_ASSERT ( expr ) assert(expr)

Assertion macro, used to stop execution when a critical error is encountered.

Equal to assert from assert.h if ASCON_INPUT_ASSERTS is defined.
Can also be pre-defined by the user to any custom assertion.
Otherwise does nothing.

◆ ASCON_WINDOWS

#define ASCON_WINDOWS 1

Indicator simplifying the check for the Windows platform (undefined on other platforms).

Used for internal decisions on how to inline functions.

◆ ASCON_API

#define ASCON_API __declspec(dllexport)

Marker of all the library's public API functions.

Used to add exporting indicators for DLL on Windows, empty on other platforms.

◆ ASCON_API_VERSION_MAJOR

#define ASCON_API_VERSION_MAJOR 1

Major version of this API conforming to semantic versioning.

◆ ASCON_API_VERSION_MINOR

#define ASCON_API_VERSION_MINOR 2

Minor version of this API conforming to semantic versioning.

◆ ASCON_API_VERSION_BUGFIX

#define ASCON_API_VERSION_BUGFIX 1

Bugfix/patch version of this API conforming to semantic versioning.

◆ ASCON_API_VERSION

#define ASCON_API_VERSION "1.2.1"

Version of this API conforming to semantic versioning as a string.

◆ ASCON_AEAD128_KEY_LEN

#define ASCON_AEAD128_KEY_LEN 16U

Length in bytes of the secret symmetric key used for the Ascon128 cipher.

◆ ASCON_AEAD128a_KEY_LEN

#define ASCON_AEAD128a_KEY_LEN 16U

Length in bytes of the secret symmetric key used for the Ascon128a cipher.

◆ ASCON_AEAD80pq_KEY_LEN

#define ASCON_AEAD80pq_KEY_LEN 20U

Length in bytes of the secret symmetric key used for the Ascon80pq cipher.

◆ ASCON_AEAD_NONCE_LEN

#define ASCON_AEAD_NONCE_LEN 16U

Length in bytes of the public nonce used for authenticated encryption and decryption.

◆ ASCON_AEAD_TAG_MIN_SECURE_LEN

#define ASCON_AEAD_TAG_MIN_SECURE_LEN 16U

Minimum recommended length in bytes of the authentication tag generated by the authenticated encryption and validated by the decryption.

◆ ASCON_HASH_DIGEST_LEN

#define ASCON_HASH_DIGEST_LEN 32U

Length in bytes of the digest generated by the fixed-size (non-xof) hash function.

◆ ASCON_HASHA_DIGEST_LEN

#define ASCON_HASHA_DIGEST_LEN ASCON_HASH_DIGEST_LEN

Length in bytes of the digest generated by the fixed-size (non-xof) hasha function.

◆ ASCON_RATE

#define ASCON_RATE 8U

Number of bytes the cipher can process at the time in AEAD128 mode and hashing.

◆ ASCON_DOUBLE_RATE

#define ASCON_DOUBLE_RATE (2U * ASCON_RATE)

Number of bytes the cipher can process at the time in AEAD128a mode.

The AEAD128a cipher absorbs blocks twice the standard rate size.

◆ ASCON_TAG_OK

#define ASCON_TAG_OK true

The tag is valid thus the associated data and ciphertext were intact.

◆ ASCON_TAG_INVALID

#define ASCON_TAG_INVALID false

The tag is invalid thus the associated data and decrypted data should be ignored.

Typedef Documentation

◆ ascon_sponge_t

typedef struct ascon_sponge ascon_sponge_t

Internal cipher sponge state (320 bits).

◆ ascon_bufstate_t

typedef struct ascon_bufstate ascon_bufstate_t

Internal cipher sponge state associated with a buffer holding for less-than-rate updates.

Used for the Init-Update-Final implementation.

◆ ascon_hash_ctx_t

typedef ascon_bufstate_t ascon_hash_ctx_t

Cipher context for hashing.

◆ ascon_aead_ctx_t

typedef struct ascon_aead_ctx ascon_aead_ctx_t

Cipher context for authenticated encryption and validated decryption.

Half of this context's size is the cipher's sponge state, the remaining part is holding the key and the buffering of online data (and some padding).

Function Documentation

◆ ascon_aead128_encrypt()

ASCON_API void ascon_aead128_encrypt	(	uint8_t *	ciphertext,
		uint8_t *	tag,
		const uint8_t	key[ASCON_AEAD128_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	plaintext,
		size_t	assoc_data_len,
		size_t	plaintext_len,
		size_t	tag_len
	)

Offline symmetric encryption using Ascon128.

Encrypts the data which is already available as a whole in a contiguous buffer, authenticating any optional associated data in the process. Provides the ciphertext and the authentication tag as output.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Warning: The nonce must be unique, as the strength of the AEAD is based on its uniqueness.; Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[out]	ciphertext	encrypted data with the same length as the plaintext, thus `plaintext_len` will be written in this buffer. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	key	secret key of ASCON_AEAD128_KEY_LEN. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be authenticated with the same tag but not encrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	plaintext	data to be encrypted into `ciphertext`.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. Can be 0 (not recommended, see warning).
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

◆ ascon_aead128_init()

ASCON_API void ascon_aead128_init	(	ascon_aead_ctx_t *	ctx,
		const uint8_t	key[ASCON_AEAD128_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN]
	)

Online symmetric encryption/decryption using Ascon128, initialisation.

Prepares to start a new encryption or decryption session for plaintext or ciphertext and associated data being provided one chunk at the time.

The key and nonce are copied/absorbed into the internal state, so they can be deleted from their original location after this function returns.

The calling order for encryption/decryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_encrypt_update() / ascon_aead128_decrypt_update() - 0 or more times, see warning
ascon_aead128_encrypt_final() / ascon_aead128_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during the ascon_aead128_encrypt_final() or ascon_aead128_decrypt_final() call. In case the encryption or decryption session is interrupted and never finalised, clear the context with ascon_aead_cleanup() to erase the key copy.; Do not mix Init-Update-Final functions across ciphers.

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	key	secret key of ASCON_AEAD128_KEY_LEN bytes. Not NULL
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes. Not NULL.

◆ ascon_aead128_assoc_data_update()

ASCON_API void ascon_aead128_assoc_data_update	(	ascon_aead_ctx_t *	ctx,
		const uint8_t *	assoc_data,
		size_t	assoc_data_len
	)

Online symmetric encryption/decryption using Ascon128, feeding associated data.

Feeds a chunk of associated data to the already initialised encryption or decryption session. The data will be authenticated by the tag provided by the final function, but not encrypted or decrypted.

In case of no associated data at all to be authenticated/validated, this function can either be skipped completely or called (also many times) with assoc_data_len set to 0. Iff that is the case, assoc_data can be set to NULL.

After calling ascon_aead128_encrypt_update() or ascon_aead128_decrypt_update(), this function must not be used anymore on the same context.

The calling order for encryption/decryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_encrypt_update() / ascon_aead128_decrypt_update() - 0 or more times, see warning
ascon_aead128_encrypt_final() / ascon_aead128_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	assoc_data	data to be authenticated/validated with the same tag but not encrypted/decrypted. May be NULL iff `assoc_data_len` is 0.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. May be 0.

◆ ascon_aead128_encrypt_update()

ASCON_API size_t ascon_aead128_encrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		const uint8_t *	plaintext,
		size_t	plaintext_len
	)

Online symmetric encryption using Ascon128, feeding plaintext and getting ciphertext.

Feeds a chunk of plaintext data to the encryption session after any optional associated data has been processed. The plaintext will be encrypted and provided as ciphertext in buffered chunks of ASCON_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for encryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_encrypt_update() - 0 or more times, see warning
ascon_aead128_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	ciphertext	encrypted data, buffered into chunks. This function will write a multiple of ASCON_RATE bytes in the interval [0, `plaintext_len` + ASCON_RATE[ into `ciphertext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	plaintext	data to be encrypted into `ciphertext`. All of the plaintext will be processed, even if the function provides less than `plaintext_len` output bytes. They are just buffered. Not NULL.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. May be 0.

Returns: number of bytes written into ciphertext. The value is a multiple of ASCON_RATE in [0, plaintext_len + ASCON_RATE[.

◆ ascon_aead128_encrypt_final()

ASCON_API size_t ascon_aead128_encrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		uint8_t *	tag,
		size_t	tag_len
	)

Online symmetric encryption using Ascon128, finalisation and tag generation.

Finalises the authenticated encryption by returning any remaining buffered ciphertext and the authentication tag. The total ciphertext length is equal to the total plaintext length.

It will securely erase the content of the ctx struct before returning.

The calling order for encryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_encrypt_update() - 0 or more times, see warning
ascon_aead128_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the encryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	ciphertext	trailing encrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_RATE[ bytes into `ciphertext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

Returns: number of bytes written into ciphertext. The value is in the interval [0, ASCON_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_aead128_decrypt()

ASCON_API bool ascon_aead128_decrypt	(	uint8_t *	plaintext,
		const uint8_t	key[ASCON_AEAD128_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	ciphertext,
		const uint8_t *	expected_tag,
		size_t	assoc_data_len,
		size_t	ciphertext_len,
		size_t	expected_tag_len
	)

Offline symmetric decryption using Ascon128.

Decrypts the data which is already available as a whole in a contiguous buffer, validating any optional associated data in the process. Provides the plaintext and the validity of the authentication tag as output. The total plaintext length is equal to the total ciphertext length.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Parameters

[out]	plaintext	decrypted data with the same length as the ciphertext, thus `ciphertext_len` will be written in this buffer. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	key	secret key of ASCON_AEAD128_KEY_LEN bytes. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be validated with the same tag but not decrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	ciphertext	data to be decrypted into `plaintext`.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. Can be 0 (not recommended, see warning of ascon_aead128_encrypt()).
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: the answer to the question "is tha tag valid?", thus true (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_aead128_decrypt_update()

ASCON_API size_t ascon_aead128_decrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		const uint8_t *	ciphertext,
		size_t	ciphertext_len
	)

Online symmetric decryption using Ascon128, feeding ciphertext and getting plaintext.

Feeds a chunk of ciphertext data to the decryption session after any optional associated data has been processed. The ciphertext will be decrypted and provided back in buffered chunks of ASCON_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for decryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_decrypt_update() - 0 or more times, see warning
ascon_aead128_decrypt_final() - once only

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	plaintext	decrypted data, buffered into chunks. This function will write a multiple of ASCON_RATE bytes in the interval [0, `ciphertext_len` + ASCON_RATE[ into `plaintext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	ciphertext	data to be decrypted into `plaintext`. All of the ciphertext will be processed, even if the function provides less than `ciphertext_len` output bytes. They are just buffered. Not NULL.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. May be 0.

Returns: number of bytes written into plaintext. The value is a multiple of ASCON_RATE in [0, ciphertext_len + ASCON_RATE[.

◆ ascon_aead128_decrypt_final()

ASCON_API size_t ascon_aead128_decrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		bool *	is_tag_valid,
		const uint8_t *	expected_tag,
		size_t	expected_tag_len
	)

Online symmetric decryption using Ascon128, finalisation and tag validation.

Finalises the authenticated decryption by returning any remaining buffered plaintext and the validity of the authentication tag. The total plaintext length is equal to the total ciphertext length.

It will securely erase the content of the ctx struct before returning.

The calling order for decryption is:

ascon_aead128_init() - once only
ascon_aead128_assoc_data_update() - 0 or more times
ascon_aead128_decrypt_update() - 0 or more times, see warning
ascon_aead128_decrypt_final() - once only

Warning: A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the decryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	plaintext	trailing decrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_RATE[ bytes into `plaintext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	is_tag_valid	the answer to the question "is the tag valid?", thus `true` (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. `false` (== ASCON_TAG_INVALID) otherwise.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: number of bytes written into plaintext. The value is in the interval [0, ASCON_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_aead_cleanup()

ASCON_API void ascon_aead_cleanup ( ascon_aead_ctx_t * ctx )

Security cleanup of the AEAD context, in case the online processing is not completed to the end.

Use this function only when something goes wrong between the calls of online encryption or decryption and you never call the ascon_aead*_encrypt_final() or ascon_aead*_decrypt_final() functions of the cipher you are currently using (because these 2 functions perform the cleanup automatically).

This is to prevent any information (especially the key!) to leak through the context in case an encryption/decryption transaction is rolled back/abruptly terminated.

Parameters

[in,out] ctx to erase.

◆ ascon_aead128a_encrypt()

ASCON_API void ascon_aead128a_encrypt	(	uint8_t *	ciphertext,
		uint8_t *	tag,
		const uint8_t	key[ASCON_AEAD128_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	plaintext,
		size_t	assoc_data_len,
		size_t	plaintext_len,
		size_t	tag_len
	)

Offline symmetric encryption using Ascon128a, which uses a double data rate compared to Ascon128.

Encrypts the data which is already available as a whole in a contiguous buffer, authenticating any optional associated data in the process. Provides the ciphertext and the authentication tag as output.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Warning: The nonce must be unique, as the strength of the AEAD is based on its uniqueness.; Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[out]	ciphertext	encrypted data with the same length as the plaintext, thus `plaintext_len` will be written in this buffer. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	key	secret key of ASCON_AEAD128a_KEY_LEN bytes. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be authenticated with the same tag but not encrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	plaintext	data to be encrypted into `ciphertext`.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. Can be 0 (not recommended, see warning).
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

◆ ascon_aead128a_init()

ASCON_API void ascon_aead128a_init	(	ascon_aead_ctx_t *	ctx,
		const uint8_t	key[ASCON_AEAD128a_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN]
	)

Online symmetric encryption/decryption using Ascon128a, initialisation.

Prepares to start a new encryption or decryption session for plaintext or ciphertext and associated data being provided one chunk at the time.

The key and nonce are copied/absorbed into the internal state, so they can be deleted from their original location after this function returns.

The calling order for encryption/decryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_encrypt_update() / ascon_aead128a_decrypt_update() - 0 or more times, see warning
ascon_aead128a_encrypt_final() / ascon_aead128a_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during the ascon_aead128a_encrypt_final() or ascon_aead128a_decrypt_final() call. In case the encryption or decryption session is interrupted and never finalised, clear the context with ascon_aead_cleanup() to erase the key copy.; Do not mix Init-Update-Final functions across ciphers.

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	key	secret key of ASCON_AEAD128a_KEY_LEN bytes. Not NULL
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes. Not NULL.

◆ ascon_aead128a_assoc_data_update()

ASCON_API void ascon_aead128a_assoc_data_update	(	ascon_aead_ctx_t *	ctx,
		const uint8_t *	assoc_data,
		size_t	assoc_data_len
	)

Online symmetric encryption/decryption using Ascon128a, feeding associated data.

Feeds a chunk of associated data to the already initialised encryption or decryption session. The data will be authenticated by the tag provided by the final function, but not encrypted or decrypted.

In case of no associated data at all to be authenticated/validated, this function can either be skipped completely or called (also many times) with assoc_data_len set to 0. Iff that is the case, assoc_data can be set to NULL.

After calling ascon_aead128a_encrypt_update() or ascon_aead128a_decrypt_update(), this function must not be used anymore on the same context.

The calling order for encryption/decryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_encrypt_update() / ascon_aead128a_decrypt_update() - 0 or more times, see warning
ascon_aead128a_encrypt_final() / ascon_aead128a_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	assoc_data	data to be authenticated/validated with the same tag but not encrypted/decrypted. May be NULL iff `assoc_data_len` is 0.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. May be 0.

◆ ascon_aead128a_encrypt_update()

ASCON_API size_t ascon_aead128a_encrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		const uint8_t *	plaintext,
		size_t	plaintext_len
	)

Online symmetric encryption using Ascon128a, feeding plaintext and getting ciphertext.

Feeds a chunk of plaintext data to the encryption session after any optional associated data has been processed. The plaintext will be encrypted and provided as ciphertext in buffered chunks of ASCON_DOUBLE_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for encryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_encrypt_update() - 0 or more times, see warning
ascon_aead128a_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	ciphertext	encrypted data, buffered into chunks. This function will write a multiple of ASCON_DOUBLE_RATE bytes in the interval [0, `plaintext_len` + ASCON_DOUBLE_RATE[ into `ciphertext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	plaintext	data to be encrypted into `ciphertext`. All of the plaintext will be processed, even if the function provides less than `plaintext_len` output bytes. They are just buffered. Not NULL.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. May be 0.

Returns: number of bytes written into ciphertext. The value is a multiple of ASCON_RATE in [0, plaintext_len + ASCON_DOUBLE_RATE[.

◆ ascon_aead128a_encrypt_final()

ASCON_API size_t ascon_aead128a_encrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		uint8_t *	tag,
		size_t	tag_len
	)

Online symmetric encryption using Ascon128a, finalisation and tag generation.

Finalises the authenticated encryption by returning any remaining buffered ciphertext and the authentication tag. The total ciphertext length is equal to the total plaintext length.

It will securely erase the content of the ctx struct before returning.

The calling order for encryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_encrypt_update() - 0 or more times, see warning
ascon_aead128a_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the encryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	ciphertext	trailing encrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_DOUBLE_RATE[ bytes into `ciphertext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

Returns: number of bytes written into ciphertext. The value is in the interval [0, ASCON_DOUBLE_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_aead128a_decrypt()

ASCON_API bool ascon_aead128a_decrypt	(	uint8_t *	plaintext,
		const uint8_t	key[ASCON_AEAD128a_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	ciphertext,
		const uint8_t *	expected_tag,
		size_t	assoc_data_len,
		size_t	ciphertext_len,
		size_t	expected_tag_len
	)

Offline symmetric decryption using Ascon128a, which uses a double data rate compared to Ascon128.

Decrypts the data which is already available as a whole in a contiguous buffer, validating any optional associated data in the process. Provides the plaintext and the validity of the authentication tag as output. The total plaintext length is equal to the total ciphertext length.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Parameters

[out]	plaintext	decrypted data with the same length as the ciphertext, thus `ciphertext_len` will be written in this buffer. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	key	secret key of ASCON_AEAD128a_KEY_LEN bytes. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be validated with the same tag but not decrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	ciphertext	data to be decrypted into `plaintext`.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. Can be 0 (not recommended, see warning of ascon_aead128_encrypt()).
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: the answer to the question "is tha tag valid?", thus true (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_aead128a_decrypt_update()

ASCON_API size_t ascon_aead128a_decrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		const uint8_t *	ciphertext,
		size_t	ciphertext_len
	)

Online symmetric decryption using Ascon128a, feeding ciphertext and getting plaintext.

Feeds a chunk of ciphertext data to the decryption session after any optional associated data has been processed. The ciphertext will be decrypted and provided back in buffered chunks of ASCON_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for decryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_decrypt_update() - 0 or more times, see warning
ascon_aead128a_decrypt_final() - once only

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	plaintext	decrypted data, buffered into chunks. This function will write a multiple of ASCON_DOUBLE_RATE bytes in the interval [0, `ciphertext_len` + ASCON_DOUBLE_RATE[ into `plaintext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	ciphertext	data to be decrypted into `plaintext`. All of the ciphertext will be processed, even if the function provides less than `ciphertext_len` output bytes. They are just buffered. Not NULL.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. May be 0.

Returns: number of bytes written into plaintext. The value is a multiple of ASCON_DOUBLE_RATE in [0, ciphertext_len + ASCON_DOUBLE_RATE[.

◆ ascon_aead128a_decrypt_final()

ASCON_API size_t ascon_aead128a_decrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		bool *	is_tag_valid,
		const uint8_t *	expected_tag,
		size_t	expected_tag_len
	)

Online symmetric decryption using Ascon128a, finalisation and tag validation.

Finalises the authenticated decryption by returning any remaining buffered plaintext and the validity of the authentication tag. The total plaintext length is equal to the total ciphertext length.

It will securely erase the content of the ctx struct before returning.

The calling order for decryption is:

ascon_aead128a_init() - once only
ascon_aead128a_assoc_data_update() - 0 or more times
ascon_aead128a_decrypt_update() - 0 or more times, see warning
ascon_aead128a_decrypt_final() - once only

Warning: A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the decryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	plaintext	trailing decrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_DOUBLE_RATE[ bytes into `plaintext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	is_tag_valid	the answer to the question "is the tag valid?", thus `true` (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. `false` (== ASCON_TAG_INVALID) otherwise.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: number of bytes written into plaintext. The value is in the interval [0, ASCON_DOUBLE_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_aead80pq_encrypt()

ASCON_API void ascon_aead80pq_encrypt	(	uint8_t *	ciphertext,
		uint8_t *	tag,
		const uint8_t	key[ASCON_AEAD80pq_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	plaintext,
		size_t	assoc_data_len,
		size_t	plaintext_len,
		size_t	tag_len
	)

Offline symmetric encryption using Ascon80pq, which uses a larger key.

Encrypts the data which is already available as a whole in a contiguous buffer, authenticating any optional associated data in the process. Provides the ciphertext and the authentication tag as output.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Warning: The nonce must be unique, as the strength of the AEAD is based on its uniqueness.; Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[out]	ciphertext	encrypted data with the same length as the plaintext, thus `plaintext_len` will be written in this buffer. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	key	secret key of ASCON_AEAD80pq_KEY_LEN bytes. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be authenticated with the same tag but not encrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	plaintext	data to be encrypted into `ciphertext`.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. Can be 0 (not recommended, see warning).
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

◆ ascon_aead80pq_init()

ASCON_API void ascon_aead80pq_init	(	ascon_aead_ctx_t *	ctx,
		const uint8_t	key[ASCON_AEAD80pq_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN]
	)

Online symmetric encryption/decryption using Ascon80pq, initialisation - note that a larger key is used compared to Ascon128 and Ascon128a.

Prepares to start a new encryption or decryption session for plaintext or ciphertext and associated data being provided one chunk at the time.

The key and nonce are copied/absorbed into the internal state, so they can be deleted from their original location after this function returns.

The calling order for encryption/decryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_encrypt_update() / ascon_aead80pq_decrypt_update() - 0 or more times, see warning
ascon_aead80pq_encrypt_final() / ascon_aead80pq_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during the ascon_aead80pq_encrypt_final() or ascon_aead80pq_decrypt_final() call. In case the encryption or decryption session is interrupted and never finalised, clear the context with ascon_aead_cleanup() to erase the key copy.; Do not mix Init-Update-Final functions across ciphers.

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	key	secret key of ASCON_AEAD80pq_KEY_LEN bytes. Not NULL
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes. Not NULL.

◆ ascon_aead80pq_assoc_data_update()

ASCON_API void ascon_aead80pq_assoc_data_update	(	ascon_aead_ctx_t *	ctx,
		const uint8_t *	assoc_data,
		size_t	assoc_data_len
	)

Online symmetric encryption/decryption using Ascon80pq, feeding associated data.

Feeds a chunk of associated data to the already initialised encryption or decryption session. The data will be authenticated by the tag provided by the final function, but not encrypted or decrypted.

In case of no associated data at all to be authenticated/validated, this function can either be skipped completely or called (also many times) with assoc_data_len set to 0. Iff that is the case, assoc_data can be set to NULL.

After calling ascon_aead80pq_encrypt_update() or ascon_aead80pq_decrypt_update(), this function must not be used anymore on the same context.

The calling order for encryption/decryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_encrypt_update() / ascon_aead80pq_decrypt_update() - 0 or more times, see warning
ascon_aead80pq_encrypt_final() / ascon_aead80pq_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption/decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[in]	assoc_data	data to be authenticated/validated with the same tag but not encrypted/decrypted. May be NULL iff `assoc_data_len` is 0.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. May be 0.

◆ ascon_aead80pq_encrypt_update()

ASCON_API size_t ascon_aead80pq_encrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		const uint8_t *	plaintext,
		size_t	plaintext_len
	)

Online symmetric encryption using Ascon80pq, feeding plaintext and getting ciphertext.

Feeds a chunk of plaintext data to the encryption session after any optional associated data has been processed. The plaintext will be encrypted and provided as ciphertext in buffered chunks of ASCON_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for encryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_encrypt_update() - 0 or more times, see warning
ascon_aead80pq_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	ciphertext	encrypted data, buffered into chunks. This function will write a multiple of ASCON_RATE bytes in the interval [0, `plaintext_len` + ASCON_RATE[ into `ciphertext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `plaintext` to encrypt the plaintext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	plaintext	data to be encrypted into `ciphertext`. All of the plaintext will be processed, even if the function provides less than `plaintext_len` output bytes. They are just buffered. Not NULL.
[in]	plaintext_len	length of the data pointed by `plaintext` in bytes. May be 0.

Returns: number of bytes written into ciphertext. The value is a multiple of ASCON_RATE in [0, plaintext_len + ASCON_RATE[.

◆ ascon_aead80pq_encrypt_final()

ASCON_API size_t ascon_aead80pq_encrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	ciphertext,
		uint8_t *	tag,
		size_t	tag_len
	)

Online symmetric encryption using Ascon80pq, finalisation and tag generation.

Finalises the authenticated encryption by returning any remaining buffered ciphertext and the authentication tag. The total ciphertext length is equal to the total plaintext length.

It will securely erase the content of the ctx struct before returning.

The calling order for encryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_encrypt_update() - 0 or more times, see warning
ascon_aead80pq_encrypt_final() - once only

Warning: Using the AEAD to just authenticate any associated data with no plaintext to be encrypted is not recommended as the AEAD algorithm is not designed for that. Instead, use the Ascon hashing or xof functions in the form Hash(key || msg).; A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the encryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the encryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	ciphertext	trailing encrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_RATE[ bytes into `ciphertext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	tag_len	length of the tag to generate in bytes. At least ASCON_AEAD_TAG_MIN_SECURE_LEN is recommended for security.

Returns: number of bytes written into ciphertext. The value is in the interval [0, ASCON_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_aead80pq_decrypt()

ASCON_API bool ascon_aead80pq_decrypt	(	uint8_t *	plaintext,
		const uint8_t	key[ASCON_AEAD80pq_KEY_LEN],
		const uint8_t	nonce[ASCON_AEAD_NONCE_LEN],
		const uint8_t *	assoc_data,
		const uint8_t *	ciphertext,
		const uint8_t *	expected_tag,
		size_t	assoc_data_len,
		size_t	ciphertext_len,
		size_t	expected_tag_len
	)

Offline symmetric decryption using Ascon80pq, which uses a larger key compared to Ascon128.

Decrypts the data which is already available as a whole in a contiguous buffer, validating any optional associated data in the process. Provides the plaintext and the validity of the authentication tag as output. The total plaintext length is equal to the total ciphertext length.

In case of no associated data at all to be authenticated, set assoc_data_len to 0. Iff that is the case, assoc_data can be set to NULL.

Parameters

[out]	plaintext	decrypted data with the same length as the ciphertext, thus `ciphertext_len` will be written in this buffer. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	key	secret key of ASCON_AEAD80pq_KEY_LEN bytes. Not NULL.
[in]	nonce	public unique nonce of ASCON_AEAD_NONCE_LEN bytes.
[in]	assoc_data	data to be validated with the same tag but not decrypted. Can be NULL iff `assoc_data_len` is 0.
[in]	ciphertext	data to be decrypted into `plaintext`.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	assoc_data_len	length of the data pointed by `assoc_data` in bytes. Can be 0.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. Can be 0 (not recommended, see warning of ascon_aead128_encrypt()).
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: the answer to the question "is tha tag valid?", thus true (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_aead80pq_decrypt_update()

ASCON_API size_t ascon_aead80pq_decrypt_update	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		const uint8_t *	ciphertext,
		size_t	ciphertext_len
	)

Online symmetric decryption using Ascon80pq, feeding ciphertext and getting plaintext.

Feeds a chunk of ciphertext data to the decryption session after any optional associated data has been processed. The ciphertext will be decrypted and provided back in buffered chunks of ASCON_RATE bytes.

It will automatically finalise the absorption of any associated data, so no new associated data could be processed after this function is called.

The calling order for decryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_decrypt_update() - 0 or more times, see warning
ascon_aead80pq_decrypt_final() - once only

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. Not NULL.
[out]	plaintext	decrypted data, buffered into chunks. This function will write a multiple of ASCON_RATE bytes in the interval [0, `ciphertext_len` + ASCON_RATE[ into `plaintext`. The exact number of written bytes is indicated by the return value. This pointer may also point to the same location as `ciphertext` to decrypt the ciphertext in-place, sparing on memory instead of writing into a separate output buffer. Not NULL.
[in]	ciphertext	data to be decrypted into `plaintext`. All of the ciphertext will be processed, even if the function provides less than `ciphertext_len` output bytes. They are just buffered. Not NULL.
[in]	ciphertext_len	length of the data pointed by `ciphertext` in bytes. May be 0.

Returns: number of bytes written into plaintext. The value is a multiple of ASCON_RATE in [0, ciphertext_len + ASCON_RATE[.

◆ ascon_aead80pq_decrypt_final()

ASCON_API size_t ascon_aead80pq_decrypt_final	(	ascon_aead_ctx_t *	ctx,
		uint8_t *	plaintext,
		bool *	is_tag_valid,
		const uint8_t *	expected_tag,
		size_t	expected_tag_len
	)

Online symmetric decryption using Ascon80pq, finalisation and tag validation.

Finalises the authenticated decryption by returning any remaining buffered plaintext and the validity of the authentication tag. The total plaintext length is equal to the total ciphertext length.

It will securely erase the content of the ctx struct before returning.

The calling order for decryption is:

ascon_aead80pq_init() - once only
ascon_aead80pq_assoc_data_update() - 0 or more times
ascon_aead80pq_decrypt_update() - 0 or more times, see warning
ascon_aead80pq_decrypt_final() - once only

Warning: A copy of the secret key is kept in the ctx struct and securely erased during this function call. In case the decryption session is interrupted and never finalised (this function is never called), clear the context with ascon_aead_cleanup() to erase the key copy.

Parameters

[in,out]	ctx	the decryption context, handling the cipher state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	plaintext	trailing decrypted data still available in the buffer of the buffered updating. This function will write [0, ASCON_RATE[ bytes into `plaintext`. The exact number of written bytes is indicated by the return value. Not NULL.
[out]	is_tag_valid	the answer to the question "is the tag valid?", thus `true` (== ASCON_TAG_OK) if the validation of the tag is correct, thus the associated data and ciphertext are intact and authentic. `false` (== ASCON_TAG_INVALID) otherwise.
[in]	expected_tag	Message Authentication Code (MAC, a.k.a. cryptographic tag, fingerprint), used to validate the integrity and authenticity of the associated data and ciphertext. Has `tag_len` bytes. Not NULL.
[in]	expected_tag_len	length of the `tag` to check in bytes. It should be the same length as generated during the encryption but it can be shorter (although it's not recommended).

Returns: number of bytes written into plaintext. The value is in the interval [0, ASCON_RATE[, i.e. whatever remained in the buffer after the last update call.

◆ ascon_hash()

ASCON_API void ascon_hash	(	uint8_t	digest[ASCON_HASH_DIGEST_LEN],
		const uint8_t *	data,
		size_t	data_len
	)

Offline Ascon-Hash with fixed digest length.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Parameters

[out]	digest	fingerprint of the message, output of the hash function, of ASCON_HASH_DIGEST_LEN bytes.
[in]	data	message fed into the hash function.
[in]	data_len	length of `data` in bytes.

◆ ascon_hasha()

ASCON_API void ascon_hasha	(	uint8_t	digest[ASCON_HASHA_DIGEST_LEN],
		const uint8_t *	data,
		size_t	data_len
	)

Offline Ascon-Hasha with fixed digest length.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Parameters

[out]	digest	fingerprint of the message, output of the hash function, of ASCON_HASH_DIGEST_LEN bytes.
[in]	data	message fed into the hash function.
[in]	data_len	length of `data` in bytes.

◆ ascon_hash_matches()

ASCON_API bool ascon_hash_matches	(	const uint8_t	expected_digest[ASCON_HASH_DIGEST_LEN],
		const uint8_t *	data,
		size_t	data_len
	)

Offline Ascon-Hash with fixed digest length, finalisation and digest validation of the expected one.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Parameters

[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_final() or ascon_hash() function, of ASCON_HASH_DIGEST_LEN bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	data	message fed into the hash function.
[in]	data_len	length of `data` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hasha_matches()

ASCON_API bool ascon_hasha_matches	(	const uint8_t	expected_digest[ASCON_HASHA_DIGEST_LEN],
		const uint8_t *	data,
		size_t	data_len
	)

Offline Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Parameters

[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_final() or ascon_hash() function, of ASCON_HASH_DIGEST_LEN bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	data	message fed into the hash function.
[in]	data_len	length of `data` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hash_init()

ASCON_API void ascon_hash_init ( ascon_hash_ctx_t * ctx )

Online Ascon-Hash with fixed digest length, initialisation.

Prepares to start a new hashing session to get a digest of ASCON_HASH_DIGEST_LEN bytes.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: Do not mix Init-Update-Final functions of Ascon-Hash and Ascon-XOF.

Parameters

[in,out] ctx the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.

◆ ascon_hasha_init()

ASCON_API void ascon_hasha_init ( ascon_hash_ctx_t * ctx )

Online Ascon-Hasha with fixed digest length, initialisation.

Prepares to start a new hashing session to get a digest of ASCON_HASH_DIGEST_LEN bytes.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: Do not mix Init-Update-Final functions of Ascon-Hash and Ascon-XOF.

Parameters

[in,out] ctx the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.

◆ ascon_hash_update()

ASCON_API void ascon_hash_update	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	data,
		size_t	data_len
	)

Online Ascon-Hash with fixed digest length, feeding data to hash.

Feeds a chunk of data to the already initialised hashing session.

In case of no data at all to be hashed, this function can be called (also many times) with data_len set to 0. Iff that is the case, data can be set to NULL.

Uses 12-round Pb permutations during absorption and squeezing.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.
[in]	data	bytes to be hashes. May be NULL iff `data_len` is 0.
[in]	data_len	length of the `data` pointed by in bytes. May be 0.

◆ ascon_hasha_update()

ASCON_API void ascon_hasha_update	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	data,
		size_t	data_len
	)

Online Ascon-Hasha with fixed digest length, feeding data to hash.

Feeds a chunk of data to the already initialised hashing session.

In case of no data at all to be hashed, this function can be called (also many times) with data_len set to 0. Iff that is the case, data can be set to NULL.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.
[in]	data	bytes to be hashes. May be NULL iff `data_len` is 0.
[in]	data_len	length of the `data` pointed by in bytes. May be 0.

◆ ascon_hash_final()

ASCON_API void ascon_hash_final	(	ascon_hash_ctx_t *	ctx,
		uint8_t	digest[ASCON_HASH_DIGEST_LEN]
	)

Online Ascon-Hash with fixed digest length, finalisation and digest generation.

Finalises the hashing by returning the digest of the message.

Uses 12-round Pb permutations during absorption and squeezing.

Warning: In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	digest	fingerprint of the message, output of the hash function, of ASCON_HASH_DIGEST_LEN bytes.

◆ ascon_hasha_final()

ASCON_API void ascon_hasha_final	(	ascon_hash_ctx_t *	ctx,
		uint8_t	digest[ASCON_HASHA_DIGEST_LEN]
	)

Online Ascon-Hasha with fixed digest length, finalisation and digest generation.

Finalises the hashing by returning the digest of the message.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Warning: In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	digest	fingerprint of the message, output of the hash function, of ASCON_HASH_DIGEST_LEN bytes.

◆ ascon_hash_final_matches()

ASCON_API bool ascon_hash_final_matches	(	ascon_hash_ctx_t *	ctx,
		const uint8_t	expected_digest[ASCON_HASH_DIGEST_LEN]
	)

Online Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one.

Uses 12-round Pb permutations during absorption and squeezing.

Warning: In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_final() or ascon_hash() function, of ASCON_HASH_DIGEST_LEN bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hasha_final_matches()

ASCON_API bool ascon_hasha_final_matches	(	ascon_hash_ctx_t *	ctx,
		const uint8_t	expected_digest[ASCON_HASHA_DIGEST_LEN]
	)

Online Ascon-Hasha with fixed digest length, finalisation and digest validation of the expected one.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Warning: In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_final() or ascon_hash() function, of ASCON_HASH_DIGEST_LEN bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hash_xof()

ASCON_API void ascon_hash_xof	(	uint8_t *	digest,
		const uint8_t *	data,
		size_t	digest_len,
		size_t	data_len
	)

Offline Ascon-Hash with custom digest length (eXtendable Output Function, XOF).

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it of the desired length.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.

Parameters

[out]	digest	fingerprint of the message, output of the hash function, of `digest_len` bytes.
[in]	data	message fed into the hash function.
[in]	digest_len	desired length of the `digest` in bytes.
[in]	data_len	length of `data` in bytes.

◆ ascon_hasha_xof()

ASCON_API void ascon_hasha_xof	(	uint8_t *	digest,
		const uint8_t *	data,
		size_t	digest_len,
		size_t	data_len
	)

Offline Ascon-Hasha with custom digest length (eXtendable Output Function, XOF).

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it of the desired length.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.

Parameters

[out]	digest	fingerprint of the message, output of the hash function, of `digest_len` bytes.
[in]	data	message fed into the hash function.
[in]	digest_len	desired length of the `digest` in bytes.
[in]	data_len	length of `data` in bytes.

◆ ascon_hash_xof_matches()

ASCON_API bool ascon_hash_xof_matches	(	const uint8_t *	expected_digest,
		const uint8_t *	data,
		size_t	expected_digest_len,
		size_t	data_len
	)

Offline Ascon-Hash with custom digest length (eXtendable Output Function, XOF) and validation of the expected one.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it of the desired length.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.

Parameters

[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_xof_final() or ascon_hash_xof() function, of `expected_digest_len` bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	data	message fed into the hash function.
[in]	expected_digest_len	desired length of the `expected_digest` in bytes.
[in]	data_len	length of `data` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hasha_xof_matches()

ASCON_API bool ascon_hasha_xof_matches	(	const uint8_t *	expected_digest,
		const uint8_t *	data,
		size_t	expected_digest_len,
		size_t	data_len
	)

Offline Ascon-Hasha with custom digest length (eXtendable Output Function, XOF) and validation of the expected one.

Hashes the data, which is already available as a whole in a contiguous buffer, and provides the digest for it of the desired length.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.

Parameters

[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_xof_final() or ascon_hash_xof() function, of `expected_digest_len` bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	data	message fed into the hash function.
[in]	expected_digest_len	desired length of the `expected_digest` in bytes.
[in]	data_len	length of `data` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hash_xof_init()

ASCON_API void ascon_hash_xof_init ( ascon_hash_ctx_t * ctx )

Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), initialisation.

Prepares to start a new hashing session to get a digest of custom length.

Uses 12-round Pb permutations during absorption and squeezing.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: Do not mix Init-Update-Final functions of Ascon-Hash and Ascon-XOF.

Parameters

[in,out] ctx the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.

◆ ascon_hasha_xof_init()

ASCON_API void ascon_hasha_xof_init ( ascon_hash_ctx_t * ctx )

Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), initialisation.

Prepares to start a new hashing session to get a digest of custom length.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Remarks: This function can be used for keyed hashing to generate a MAC by simply prepending a secret key to the message, like ascon_hash_xof(key || msg). There is no need to build an HMAC construct around it, as it does not suffer from length-extension vulnerabilities.

Warning: Do not mix Init-Update-Final functions of Ascon-Hash and Ascon-XOF.

Parameters

[in,out] ctx the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.

◆ ascon_hash_xof_update()

ASCON_API void ascon_hash_xof_update	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	data,
		size_t	data_len
	)

Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), feeding data to hash.

Feeds a chunk of data to the already initialised hashing session.

In case of no data at all to be hashed, this function can be called (also many times) with data_len set to 0. Iff that is the case, data can be set to NULL.

Uses 12-round Pb permutations during absorption and squeezing.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.
[in]	data	bytes to be hashes. May be NULL iff `data_len` is 0.
[in]	data_len	length of the `data` pointed by in bytes. May be 0.

◆ ascon_hasha_xof_update()

ASCON_API void ascon_hasha_xof_update	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	data,
		size_t	data_len
	)

Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), feeding data to hash.

Feeds a chunk of data to the already initialised hashing session.

In case of no data at all to be hashed, this function can be called (also many times) with data_len set to 0. Iff that is the case, data can be set to NULL.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. Not NULL.
[in]	data	bytes to be hashes. May be NULL iff `data_len` is 0.
[in]	data_len	length of the `data` pointed by in bytes. May be 0.

◆ ascon_hash_xof_final()

ASCON_API void ascon_hash_xof_final	(	ascon_hash_ctx_t *	ctx,
		uint8_t *	digest,
		size_t	digest_len
	)

Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), finalisation and digest generation.

Finalises the hashing by returning the digest of the message.

Uses 12-round Pb permutations during absorption and squeezing.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.; In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	digest	fingerprint of the message, output of the hash function, of `digest_size` bytes.
[in]	digest_len	desired length of the `digest` in bytes.

◆ ascon_hasha_xof_final()

ASCON_API void ascon_hasha_xof_final	(	ascon_hash_ctx_t *	ctx,
		uint8_t *	digest,
		size_t	digest_len
	)

Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), finalisation and digest generation.

Finalises the hashing by returning the digest of the message.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Warning: To have 128 bits of security against birthday attacks (collisions), a digest length of at least 256 bits (32 bytes) is recommended. Against quantum computers, the hash size should be double the amount of wanted security bits.; In case the hashing session is interrupted and never finalised (this function is never called), clear the context with ascon_hash_cleanup() to erase any information about the hashed content, especially in case keyed hashing is performed.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[out]	digest	fingerprint of the message, output of the hash function, of `digest_size` bytes.
[in]	digest_len	desired length of the `digest` in bytes.

◆ ascon_hash_xof_final_matches()

ASCON_API bool ascon_hash_xof_final_matches	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	expected_digest,
		size_t	expected_digest_len
	)

Online Ascon-Hash with custom digest length (eXtendable Output Function, XOF), finalisation and digest validation of the expected one.

Uses 12-round Pb permutations during absorption and squeezing.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_xof_final() or ascon_hash_xof() function, of `expected_digest_len` bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	expected_digest_len	desired length of the `expected_digest` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hasha_xof_final_matches()

ASCON_API bool ascon_hasha_xof_final_matches	(	ascon_hash_ctx_t *	ctx,
		const uint8_t *	expected_digest,
		size_t	expected_digest_len
	)

Online Ascon-Hasha with custom digest length (eXtendable Output Function, XOF), finalisation and digest validation of the expected one.

Uses 8-round Pb permutations during absorption and squeezing, lighter version of the Ascon-Hash function.

Parameters

[in,out]	ctx	the hashing context, handling the hash function state and buffering of incoming data to be processed. It will be erased securely before this function returns. Not NULL.
[in]	expected_digest	expected fingerprint of the message, output of the ascon_hash_xof_final() or ascon_hash_xof() function, of `expected_digest_len` bytes. This is the digest that comes with the message and will be compared with the internally-generated one by this function.
[in]	expected_digest_len	desired length of the `expected_digest` in bytes.

Returns: the answer to the question "is the digest valid?", thus true (== ASCON_TAG_OK) if the validation of the digest is correct, thus the message is intact (and authentic if a keyed hash was performed), false (== ASCON_TAG_INVALID) otherwise.

◆ ascon_hash_cleanup()

ASCON_API void ascon_hash_cleanup ( ascon_hash_ctx_t * ctx )

Security cleanup of the hashing context, in case the online processing is not completed to the end.

Use this function only when something goes wrong between the calls of online hashing or decryption, and you never call the ascon_hash_final() or ascon_hash_xof_final() or ascon_hasha_final() or ascon_hasha_xof_final() functions (because these functions perform the cleanup automatically).

This is to prevent any information to leak through the context in case an hashing transaction is rolled back/abruptly terminated, especially parts of a key (for keyed hashing) still buffered in the context.

Parameters

[in,out] ctx to erase.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ASCON_INPUT_ASSERTS

◆ ASCON_ASSERT

◆ ASCON_WINDOWS

◆ ASCON_API

◆ ASCON_API_VERSION_MAJOR

◆ ASCON_API_VERSION_MINOR

◆ ASCON_API_VERSION_BUGFIX

◆ ASCON_API_VERSION

◆ ASCON_AEAD128_KEY_LEN

◆ ASCON_AEAD128a_KEY_LEN

◆ ASCON_AEAD80pq_KEY_LEN

◆ ASCON_AEAD_NONCE_LEN

◆ ASCON_AEAD_TAG_MIN_SECURE_LEN

◆ ASCON_HASH_DIGEST_LEN

◆ ASCON_HASHA_DIGEST_LEN

◆ ASCON_RATE

◆ ASCON_DOUBLE_RATE

◆ ASCON_TAG_OK

◆ ASCON_TAG_INVALID

Typedef Documentation

◆ ascon_sponge_t

◆ ascon_bufstate_t

◆ ascon_hash_ctx_t

◆ ascon_aead_ctx_t

Function Documentation

◆ ascon_aead128_encrypt()

◆ ascon_aead128_init()

◆ ascon_aead128_assoc_data_update()

◆ ascon_aead128_encrypt_update()

◆ ascon_aead128_encrypt_final()

◆ ascon_aead128_decrypt()

◆ ascon_aead128_decrypt_update()

◆ ascon_aead128_decrypt_final()

◆ ascon_aead_cleanup()

◆ ascon_aead128a_encrypt()

◆ ascon_aead128a_init()

◆ ascon_aead128a_assoc_data_update()

◆ ascon_aead128a_encrypt_update()

◆ ascon_aead128a_encrypt_final()

◆ ascon_aead128a_decrypt()

◆ ascon_aead128a_decrypt_update()

◆ ascon_aead128a_decrypt_final()

◆ ascon_aead80pq_encrypt()

◆ ascon_aead80pq_init()

◆ ascon_aead80pq_assoc_data_update()

◆ ascon_aead80pq_encrypt_update()

◆ ascon_aead80pq_encrypt_final()

◆ ascon_aead80pq_decrypt()

◆ ascon_aead80pq_decrypt_update()

◆ ascon_aead80pq_decrypt_final()

◆ ascon_hash()

◆ ascon_hasha()

◆ ascon_hash_matches()

◆ ascon_hasha_matches()

◆ ascon_hash_init()

◆ ascon_hasha_init()

◆ ascon_hash_update()

◆ ascon_hasha_update()

◆ ascon_hash_final()

◆ ascon_hasha_final()

◆ ascon_hash_final_matches()

◆ ascon_hasha_final_matches()

◆ ascon_hash_xof()

◆ ascon_hasha_xof()

◆ ascon_hash_xof_matches()

◆ ascon_hasha_xof_matches()

◆ ascon_hash_xof_init()

◆ ascon_hasha_xof_init()

◆ ascon_hash_xof_update()

◆ ascon_hasha_xof_update()

◆ ascon_hash_xof_final()

◆ ascon_hasha_xof_final()

◆ ascon_hash_xof_final_matches()

◆ ascon_hasha_xof_final_matches()