saturnin.h File Reference

Saturnin authenticated encryption algorithm. More...

#include "aead-common.h"

Go to the source code of this file.

Data Structures
union	saturnin_hash_state_t
	State information for SATURNIN-Hash incremental modes. More...

Macros
#define	SATURNIN_KEY_SIZE   32
	Size of the key for all SATURNIN family members.
#define	SATURNIN_TAG_SIZE   32
	Size of the authentication tag for SATURNIN-CTR-Cascade or the total size of the ciphertext for SATURNIN-Short.
#define	SATURNIN_NONCE_SIZE   16
	Size of the nonce for all SATURNIN family members.
#define	SATURNIN_HASH_SIZE   32
	Size of the hash for SATURNIN-Hash.

Functions
int	saturnin_aead_encrypt (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 SATURNIN-CTR-Cascade. More...
int	saturnin_aead_decrypt (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 SATURNIN-CTR-Cascade. More...
int	saturnin_short_aead_encrypt (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 SATURNIN-Short. More...
int	saturnin_short_aead_decrypt (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 SATURNIN-Short. More...
int	saturnin_hash (unsigned char *out, const unsigned char *in, unsigned long long inlen)
	Hashes a block of input data with SATURNIN to generate a hash value. More...
void	saturnin_hash_init (saturnin_hash_state_t *state)
	Initializes the state for an SATURNIN-Hash hashing operation. More...
void	saturnin_hash_update (saturnin_hash_state_t *state, const unsigned char *in, unsigned long long inlen)
	Updates an SATURNIN-Hash state with more input data. More...
void	saturnin_hash_finalize (saturnin_hash_state_t *state, unsigned char *out)
	Returns the final hash value from an SATURNIN-Hash hashing operation. More...

Variables
aead_cipher_t const	saturnin_cipher
	Meta-information block for the SATURNIN-CTR-Cascade cipher.
aead_cipher_t const	saturnin_short_cipher
	Meta-information block for the SATURNIN-Short cipher.
aead_hash_algorithm_t const	saturnin_hash_algorithm
	Meta-information block for SATURNIN-Hash.

Detailed Description

Saturnin authenticated encryption algorithm.

The Saturnin family consists of two members: SATURNIN-CTR-Cascade and SATURNIN-Short. Both take a 256-bit key and a 128-bit nonce. Internally they use a 256-bit block cipher similar in construction to AES.

SATURNIN-Short does not support associated data or plaintext packets with more than 15 bytes. This makes it very efficient on short packets with only a single block operation involved.

This implementation of SATURNIN-Short will return an error if the caller supplies associated data or more than 15 bytes of plaintext.

References: https://project.inria.fr/saturnin/

Function Documentation

int saturnin_aead_decrypt	(	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 SATURNIN-CTR-Cascade.

Parameters

m	Buffer to receive the plaintext message on output.
mlen	Receives the length of the plaintext message on output.
nsec	Secret nonce - not used by this algorithm.
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 32 byte 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 which must be 16 bytes in length.
k	Points to the 32 bytes of 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.

See Also

saturnin_aead_encrypt()

int saturnin_aead_encrypt	(	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 SATURNIN-CTR-Cascade.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the 32 byte 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 - not used by this algorithm.
npub	Points to the public nonce for the packet which must be 16 bytes in length.
k	Points to the 32 bytes of the key to use to encrypt the packet.

Returns

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

See Also

saturnin_aead_decrypt()

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

Hashes a block of input data with SATURNIN to generate a hash value.

Parameters

out	Buffer to receive the hash output which must be at least SATURNIN_HASH_SIZE bytes in length.
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.

void saturnin_hash_finalize	(	saturnin_hash_state_t *	state,
		unsigned char *	out
	)

Returns the final hash value from an SATURNIN-Hash hashing operation.

Parameters

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

See Also

saturnin_hash_init(), saturnin_hash_update()

void saturnin_hash_init

(

saturnin_hash_state_t *

state

)

Initializes the state for an SATURNIN-Hash hashing operation.

Parameters

state

Hash state to be initialized.

See Also

saturnin_hash_update(), saturnin_hash_finalize(), saturnin_hash()

void saturnin_hash_update	(	saturnin_hash_state_t *	state,
		const unsigned char *	in,
		unsigned long long	inlen
	)

Updates an SATURNIN-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.

See Also

saturnin_hash_init(), saturnin_hash_finalize()

int saturnin_short_aead_decrypt	(	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 SATURNIN-Short.

Parameters

m	Buffer to receive the plaintext message on output. There must be at least 15 bytes of space in this buffer even if the caller expects to receive less data than that.
mlen	Receives the length of the plaintext message on output.
nsec	Secret nonce - not used by this algorithm.
c	Buffer that contains the ciphertext to decrypt.
clen	Length of the input data in bytes, which must be 32.
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, which must be zero.
npub	Points to the public nonce for the packet which must be 16 bytes in length.
k	Points to the 32 bytes of the key to use to decrypt the packet.

Returns

0 on success, -1 if the authentication tag was incorrect, or -2 if the caller supplied associated data.

See Also

saturnin_short_aead_encrypt()

int saturnin_short_aead_encrypt	(	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 SATURNIN-Short.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which is always 32.
m	Buffer that contains the plaintext message to encrypt.
mlen	Length of the plaintext message in bytes, which must be less than or equal to 15 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, which must be zero.
nsec	Secret nonce - not used by this algorithm.
npub	Points to the public nonce for the packet which must be 16 bytes in length.
k	Points to the 32 bytes of the key to use to encrypt the packet.

Returns

0 on success, or -2 if the caller supplied too many bytes of plaintext or they supplied associated data.

See Also

saturnin_short_aead_decrypt()