knot.h File Reference

KNOT authenticated encryption and hash algorithms. More...

#include "aead-common.h"

Go to the source code of this file.

Macros
#define	KNOT_AEAD_128_KEY_SIZE   16
	Size of the key for KNOT-AEAD-128-256 and KNOT-AEAD-128-384.
#define	KNOT_AEAD_128_TAG_SIZE   16
	Size of the authentication tag for KNOT-AEAD-128-256 and KNOT-AEAD-128-384.
#define	KNOT_AEAD_128_NONCE_SIZE   16
	Size of the nonce for KNOT-AEAD-128-256 and KNOT-AEAD-128-384.
#define	KNOT_AEAD_192_KEY_SIZE   24
	Size of the key for KNOT-AEAD-192-384.
#define	KNOT_AEAD_192_TAG_SIZE   24
	Size of the authentication tag for KNOT-AEAD-192-384.
#define	KNOT_AEAD_192_NONCE_SIZE   24
	Size of the nonce for KNOT-AEAD-128-256 and KNOT-AEAD-192-384.
#define	KNOT_AEAD_256_KEY_SIZE   32
	Size of the key for KNOT-AEAD-256-512.
#define	KNOT_AEAD_256_TAG_SIZE   32
	Size of the authentication tag for KNOT-AEAD-256-512.
#define	KNOT_AEAD_256_NONCE_SIZE   32
	Size of the nonce for KNOT-AEAD-128-256 and KNOT-AEAD-128-384.
#define	KNOT_HASH_256_SIZE   32
	Size of the hash for KNOT-HASH-256-256 and KNOT-HASH-256-384.
#define	KNOT_HASH_384_SIZE   48
	Size of the hash for KNOT-HASH-384-384.
#define	KNOT_HASH_512_SIZE   64
	Size of the hash for KNOT-HASH-512-512.

Functions
int	knot_aead_128_256_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 KNOT-AEAD-128-256. More...
int	knot_aead_128_256_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 KNOT-AEAD-128-256. More...
int	knot_aead_128_384_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 KNOT-AEAD-128-384. More...
int	knot_aead_128_384_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 KNOT-AEAD-128-384. More...
int	knot_aead_192_384_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 KNOT-AEAD-192-384. More...
int	knot_aead_192_384_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 KNOT-AEAD-192-384. More...
int	knot_aead_256_512_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 KNOT-AEAD-256-512. More...
int	knot_aead_256_512_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 KNOT-AEAD-256-512. More...
int	knot_hash_256_256 (unsigned char *out, const unsigned char *in, unsigned long long inlen)
	Hashes a block of input data with KNOT-HASH-256-256. More...
int	knot_hash_256_384 (unsigned char *out, const unsigned char *in, unsigned long long inlen)
	Hashes a block of input data with KNOT-HASH-256-384. More...
int	knot_hash_384_384 (unsigned char *out, const unsigned char *in, unsigned long long inlen)
	Hashes a block of input data with KNOT-HASH-384-384. More...
int	knot_hash_512_512 (unsigned char *out, const unsigned char *in, unsigned long long inlen)
	Hashes a block of input data with KNOT-HASH-512-512. More...

Variables
aead_cipher_t const	knot_aead_128_256_cipher
	Meta-information block for the KNOT-AEAD-128-256 cipher.
aead_cipher_t const	knot_aead_128_384_cipher
	Meta-information block for the KNOT-AEAD-128-384 cipher.
aead_cipher_t const	knot_aead_192_384_cipher
	Meta-information block for the KNOT-AEAD-192-384 cipher.
aead_cipher_t const	knot_aead_256_512_cipher
	Meta-information block for the KNOT-AEAD-256-512 cipher.
aead_hash_algorithm_t const	knot_hash_256_256_algorithm
	Meta-information block for the KNOT-HASH-256-256 algorithm.
aead_hash_algorithm_t const	knot_hash_256_384_algorithm
	Meta-information block for the KNOT-HASH-256-384 algorithm.
aead_hash_algorithm_t const	knot_hash_384_384_algorithm
	Meta-information block for the KNOT-HASH-384-384 algorithm.
aead_hash_algorithm_t const	knot_hash_512_512_algorithm
	Meta-information block for the KNOT-HASH-512-512 algorithm.

Detailed Description

KNOT authenticated encryption and hash algorithms.

KNOT is a family of authenticated encryption and hash algorithms built around a permutation and the MonkeyDuplex sponge construction. The family members are:

• KNOT-AEAD-128-256 with a 128-bit key, a 128-bit nonce, and a 128-bit tag, built around a 256-bit permutation. This is the primary encryption member of the family.
• KNOT-AEAD-128-384 with a 128-bit key, a 128-bit nonce, and a 128-bit tag, built around a 384-bit permutation.
• KNOT-AEAD-192-384 with a 192-bit key, a 192-bit nonce, and a 192-bit tag, built around a 384-bit permutation.
• KNOT-AEAD-256-512 with a 256-bit key, a 256-bit nonce, and a 256-bit tag, built around a 512-bit permutation.
• KNOT-HASH-256-256 with a 256-bit hash output, built around a 256-bit permutation. This is the primary hashing member of the family.
• KNOT-HASH-256-384 with a 256-bit hash output, built around a 384-bit permutation.
• KNOT-HASH-384-384 with a 384-bit hash output, built around a 384-bit permutation.
• KNOT-HASH-512-512 with a 512-bit hash output, built around a 512-bit permutation.

References: https://csrc.nist.gov/CSRC/media/Projects/lightweight-cryptography/documents/round-2/spec-doc-rnd2/knot-spec-round.pdf

Function Documentation

int knot_aead_128_256_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 KNOT-AEAD-128-256.

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 16 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 16 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

knot_aead_128_256_encrypt()

int knot_aead_128_256_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 KNOT-AEAD-128-256.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the 16 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 16 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

knot_aead_128_256_decrypt()

int knot_aead_128_384_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 KNOT-AEAD-128-384.

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 16 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 16 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

knot_aead_128_384_encrypt()

int knot_aead_128_384_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 KNOT-AEAD-128-384.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the 16 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 16 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

knot_aead_128_384_decrypt()

int knot_aead_192_384_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 KNOT-AEAD-192-384.

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 16 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 16 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

knot_aead_192_384_encrypt()

int knot_aead_192_384_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 KNOT-AEAD-192-384.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the 16 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 16 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

knot_aead_192_384_decrypt()

int knot_aead_256_512_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 KNOT-AEAD-256-512.

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 16 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 16 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

knot_aead_256_512_encrypt()

int knot_aead_256_512_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 KNOT-AEAD-256-512.

Parameters

c	Buffer to receive the output.
clen	On exit, set to the length of the output which includes the ciphertext and the 16 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 16 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

knot_aead_256_512_decrypt()

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

Hashes a block of input data with KNOT-HASH-256-256.

Parameters

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

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

Hashes a block of input data with KNOT-HASH-256-384.

Parameters

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

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

Hashes a block of input data with KNOT-HASH-384-384.

Parameters

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

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

Hashes a block of input data with KNOT-HASH-512-512.

Parameters

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