Definitions that are common across AEAD schemes. More...

#include <stddef.h>

Data Structures
struct	aead_cipher_t
	Meta-information about an AEAD cipher. More...

struct	aead_hash_algorithm_t
	Meta-information about a hash algorithm that is related to an AEAD. More...

Macros
#define	AEAD_FLAG_NONE 0x0000
	No special AEAD features.

#define	AEAD_FLAG_LITTLE_ENDIAN 0x0001
	The natural byte order of the AEAD cipher is little-endian. More...

#define	AEAD_FLAG_SC_PROTECT_KEY 0x0002
	The AEAD mode provides side-channel protection for the key.

#define	AEAD_FLAG_SC_PROTECT_ALL 0x0004
	The AEAD mode provides side-channel protection for all block operations.

Typedefs
typedef int(*	aead_cipher_encrypt_t )(unsigned char c, unsigned long long clen, const unsigned char m, unsigned long long mlen, const unsigned char ad, unsigned long long adlen, const unsigned char nsec, const unsigned char npub, const unsigned char *k)
	Encrypts and authenticates a packet with an AEAD scheme. More...

typedef int(*	aead_cipher_decrypt_t )(unsigned char m, unsigned long long mlen, unsigned char nsec, const unsigned char c, unsigned long long clen, const unsigned char ad, unsigned long long adlen, const unsigned char npub, const unsigned char *k)
	Decrypts and authenticates a packet with an AEAD scheme. More...

typedef int(*	aead_hash_t )(unsigned char out, const unsigned char in, unsigned long long inlen)
	Hashes a block of input data. More...

typedef void(*	aead_hash_init_t )(void *state)
	Initializes the state for a hashing operation. More...

typedef void(*	aead_hash_update_t )(void state, const unsigned char in, unsigned long long inlen)
	Updates a hash state with more input data. More...

typedef void(*	aead_hash_finalize_t )(void state, unsigned char out)
	Returns the final hash value from a hashing operation. More...

typedef void(*	aead_xof_absorb_t )(void state, const unsigned char in, unsigned long long inlen)
	Aborbs more input data into an XOF state. More...

typedef void(*	aead_xof_squeeze_t )(void state, unsigned char out, unsigned long long outlen)
	Squeezes output data from an XOF state. More...

Functions
int	aead_check_tag (unsigned char plaintext, unsigned long long plaintext_len, const unsigned char tag1, const unsigned char *tag2, unsigned tag_len)
	Check an authentication tag in constant time. More...

int	aead_check_tag_precheck (unsigned char plaintext, unsigned long long plaintext_len, const unsigned char tag1, const unsigned char *tag2, unsigned tag_len, int precheck)
	Check an authentication tag in constant time with a previous check. More...

Detailed Description

Definitions that are common across AEAD schemes.

AEAD stands for "Authenticated Encryption with Associated Data". It is a standard API pattern for securely encrypting and authenticating packets of data.

Macro Definition Documentation

#define AEAD_FLAG_LITTLE_ENDIAN 0x0001

The natural byte order of the AEAD cipher is little-endian.

If this flag is not present, then the natural byte order of the AEAD cipher should be assumed to be big-endian.

The natural byte order may be useful when formatting packet sequence numbers as nonces. The application needs to know whether the sequence number should be packed into the leading or trailing bytes of the nonce.

Typedef Documentation

typedef int(* aead_cipher_decrypt_t)(unsigned char *m, unsigned long long *mlen, unsigned char *nsec, const unsigned char *c, unsigned long long clen, const unsigned char *ad, unsigned long long adlen, const unsigned char *npub, const unsigned char *k)

Decrypts and authenticates a packet with an AEAD scheme.

Parameters

m	Buffer to receive the plaintext message on output.
mlen	Receives the length of the plaintext message on output.
nsec	Secret nonce - normally not used by AEAD schemes.
c	Buffer that contains the ciphertext and authentication tag to decrypt.
clen	Length of the input data in bytes, which includes the ciphertext and the authentication tag.
ad	Buffer that contains associated data to authenticate along with the packet but which does not need to be encrypted.
adlen	Length of the associated data in bytes.
npub	Points to the public nonce for the packet.
k	Points to the key to use to decrypt the packet.

Returns: 0 on success, -1 if the authentication tag was incorrect, or some other negative number if there was an error in the parameters.

typedef int(* aead_cipher_encrypt_t)(unsigned char *c, unsigned long long *clen, const unsigned char *m, unsigned long long mlen, const unsigned char *ad, unsigned long long adlen, const unsigned char *nsec, const unsigned char *npub, const unsigned char *k)

Encrypts and authenticates a packet with an AEAD scheme.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the authentication tag.
m	Buffer that contains the plaintext message to encrypt.
mlen	Length of the plaintext message in bytes.
ad	Buffer that contains associated data to authenticate along with the packet but which does not need to be encrypted.
adlen	Length of the associated data in bytes.
nsec	Secret nonce - normally not used by AEAD schemes.
npub	Points to the public nonce for the packet.
k	Points to the key to use to encrypt the packet.

Returns: 0 on success, or a negative value if there was an error in the parameters.

typedef void(* aead_hash_finalize_t)(void *state, unsigned char *out)

Returns the final hash value from a hashing operation.

Parameters

Hash	state to be finalized.
out	Points to the output buffer to receive the hash value.

typedef void(* aead_hash_init_t)(void *state)

Initializes the state for a hashing operation.

Parameters

state Hash state to be initialized.

typedef int(* aead_hash_t)(unsigned char *out, const unsigned char *in, unsigned long long inlen)

Hashes a block of input data.

Parameters

out	Buffer to receive the hash output.
in	Points to the input data to be hashed.
inlen	Length of the input data in bytes.

Returns: Returns zero on success or -1 if there was an error in the parameters.

typedef void(* aead_hash_update_t)(void *state, const unsigned char *in, unsigned long long inlen)

Updates a hash state with more input data.

Parameters

state	Hash state to be updated.
in	Points to the input data to be incorporated into the state.
inlen	Length of the input data to be incorporated into the state.

typedef void(* aead_xof_absorb_t)(void *state, const unsigned char *in, unsigned long long inlen)

Aborbs more input data into an XOF state.

Parameters

state	XOF state to be updated.
in	Points to the input data to be absorbed into the state.
inlen	Length of the input data to be absorbed into the state.

See Also: ascon_xof_init(), ascon_xof_squeeze()

typedef void(* aead_xof_squeeze_t)(void *state, unsigned char *out, unsigned long long outlen)

Squeezes output data from an XOF state.

Parameters

state	XOF state to squeeze the output data from.
out	Points to the output buffer to receive the squeezed data.
outlen	Number of bytes of data to squeeze out of the state.

Function Documentation

int aead_check_tag	(	unsigned char *	plaintext,
		unsigned long long	plaintext_len,
		const unsigned char *	tag1,
		const unsigned char *	tag2,
		unsigned	tag_len
	)

Check an authentication tag in constant time.

Parameters

plaintext	Points to the plaintext data.
plaintext_len	Length of the plaintext in bytes.
tag1	First tag to compare.
tag2	Second tag to compare.
tag_len	Length of the tags in bytes.

Returns: Returns -1 if the tag check failed or 0 if the check succeeded.

If the tag check fails, then the plaintext will also be zeroed to prevent it from being used accidentally by the application when the ciphertext was invalid.

int aead_check_tag_precheck	(	unsigned char *	plaintext,
		unsigned long long	plaintext_len,
		const unsigned char *	tag1,
		const unsigned char *	tag2,
		unsigned	tag_len,
		int	precheck
	)

Check an authentication tag in constant time with a previous check.

Parameters

plaintext	Points to the plaintext data.
plaintext_len	Length of the plaintext in bytes.
tag1	First tag to compare.
tag2	Second tag to compare.
tag_len	Length of the tags in bytes.
precheck	Set to -1 if previous check succeeded or 0 if it failed.

Returns: Returns -1 if the tag check failed or 0 if the check succeeded.

If the tag check fails, then the plaintext will also be zeroed to prevent it from being used accidentally by the application when the ciphertext was invalid.

This version can be used to incorporate other information about the correctness of the plaintext into the final result.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation