Abstract base class for authenticated ciphers. More...

#include <AuthenticatedCipher.h>

Inheritance diagram for AuthenticatedCipher:

Public Member Functions
	AuthenticatedCipher ()
	Constructs a new authenticated cipher.

virtual	~AuthenticatedCipher ()
	Destroys this authenticated cipher.

virtual size_t	tagSize () const =0
	Returns the size of the authentication tag. More...

virtual void	addAuthData (const void *data, size_t len)=0
	Adds extra data that will be authenticated but not encrypted. More...

virtual void	computeTag (void *tag, size_t len)=0
	Finalizes the encryption process and computes the authentication tag. More...

virtual bool	checkTag (const void *tag, size_t len)=0
	Finalizes the decryption process and checks the authentication tag. More...

Public Member Functions inherited from Cipher
	Cipher ()
	Constructs a new cipher object.

virtual	~Cipher ()
	Destroys this cipher object. More...

virtual size_t	keySize () const =0
	Default size of the key for this cipher, in bytes. More...

virtual size_t	ivSize () const =0
	Size of the initialization vector for this cipher, in bytes. More...

virtual bool	setKey (const uint8_t *key, size_t len)=0
	Sets the key to use for future encryption and decryption operations. More...

virtual bool	setIV (const uint8_t *iv, size_t len)=0
	Sets the initialization vector to use for future encryption and decryption operations. More...

virtual void	encrypt (uint8_t output, const uint8_t input, size_t len)=0
	Encrypts an input buffer and writes the ciphertext to an output buffer. More...

virtual void	decrypt (uint8_t output, const uint8_t input, size_t len)=0
	Decrypts an input buffer and writes the plaintext to an output buffer. More...

virtual void	clear ()=0
	Clears all security-sensitive state from this cipher. More...

Detailed Description

Abstract base class for authenticated ciphers.

This class abstracts the details of algorithms that provide Authenticated Encryption with Associated Data (AEAD). Such algorithms combine encryption with message authentication to provide a single primitive.

Authenticated ciphers have four parameters: the secret key, an initialization vector (called a "nonce" in the literature), the plaintext, and some associated data which is to be authenticated with the plaintext but not encrypted. Associated data might be sequence numbers, IP addresses, protocol versions, or other information that is not secret but is important and unique to the session.

Subclasses encrypt the plaintext content and output the ciphertext. Once all plaintext has been processed, the caller should invoke computeTag() to obtain the authentication tag to transmit with the ciphertext. When the ciphertext is later decrypted, the checkTag() function can be used to check that the data is authentic.

Reference: RFC 5116

See also: Cipher

Definition at line 28 of file AuthenticatedCipher.h.

Member Function Documentation

◆ addAuthData()

void AuthenticatedCipher::addAuthData	(	const void *	data,
		size_t	len
	)

pure virtual

Adds extra data that will be authenticated but not encrypted.

Parameters

data	The extra data to be authenticated.
len	The number of bytes of extra data to be authenticated.

This function must be called before the first call to encrypt() or decrypt(). That is, it is assumed that all extra data for authentication is available before the first payload data block and that it will be prepended to the payload for authentication. If the subclass needs to process the extra data after the payload, then it is responsible for saving data away until it is needed during computeTag() or checkTag().

This function can be called multiple times with separate extra data blocks for authentication. All such data will be concatenated into a single block for authentication purposes.

Implemented in Ascon128, Acorn128, GCMCommon, EAXCommon, and ChaChaPoly.

◆ checkTag()

bool AuthenticatedCipher::checkTag	(	const void *	tag,
		size_t	len
	)

pure virtual

Finalizes the decryption process and checks the authentication tag.

Parameters

tag	The tag value from the incoming ciphertext to be checked.
len	The length of the tag value in bytes, which may be less than tagSize().

Returns: Returns true if the tag is identical to the first len bytes of the authentication tag that was calculated during the decryption process. Returns false otherwise.

This function must be called after the final block of ciphertext is passed to decrypt() to determine if the data could be authenticated.

Note: Authenticated cipher modes usually require that if the tag could not be verified, then all of the data that was previously decrypted must be discarded. It is unwise to use the decrypted data for any purpose before it can be verified. Callers are responsible for ensuring that any data returned via previous calls to decrypt() is discarded if checkTag() returns false.