AuthenticatedSymmetricCipherBase Class Referenceabstract

Base class for authenticated encryption modes of operation. More...

`#include <authenc.h>`

Inheritance diagram for AuthenticatedSymmetricCipherBase:

## Public Member Functions

bool | IsRandomAccess () const
| Determines whether the cipher supports random access.
bool | IsSelfInverting () const
| Determines whether the cipher is self-inverting.
void | SetKey (const byte *userKey, size_t keylength, const NameValuePairs &params)
| Sets or reset the key of this object.
void | Restart ()
| Restart the hash.
void | Resynchronize (const byte *iv, int length=-1)
| Resynchronize with an IV.
void | Update (const byte *input, size_t length)
| Updates a hash with additional input.
void | ProcessData (byte *outString, const byte *inString, size_t length)
| Encrypt or decrypt an array of bytes.
void | TruncatedFinal (byte *mac, size_t macSize)
| Computes the hash of the current message.
Public Member Functions inherited from AuthenticatedSymmetricCipher
virtual lword | MaxHeaderLength () const =0
| Provides the maximum length of AAD that can be input.
virtual lword | MaxMessageLength () const =0
| Provides the maximum length of encrypted data.
virtual lword | MaxFooterLength () const
| Provides the maximum length of AAD.
virtual bool | NeedsPrespecifiedDataLengths () const
| Determines if data lengths must be specified prior to inputting data.
void | SpecifyDataLengths (lword headerLength, lword messageLength, lword footerLength=0)
| Prescribes the data lengths.
virtual void | EncryptAndAuthenticate (byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *message, size_t messageLength)
| Encrypts and calculates a MAC in one call.
virtual bool | DecryptAndVerify (byte *message, const byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *header, size_t headerLength, const byte *ciphertext, size_t ciphertextLength)
| Decrypts and verifies a MAC in one call.
virtual std::string | AlgorithmName () const
| Provides the name of this algorithm.
virtual std::string | AlgorithmProvider () const
| Retrieve the provider of this algorithm.
Public Member Functions inherited from SimpleKeyingInterface
virtual size_t | MinKeyLength () const =0
| Returns smallest valid key length.
virtual size_t | MaxKeyLength () const =0
| Returns largest valid key length.
virtual size_t | DefaultKeyLength () const =0
| Returns default key length.
virtual size_t | GetValidKeyLength (size_t keylength) const =0
| Returns a valid key length for the algorithm.
virtual bool | IsValidKeyLength (size_t keylength) const
| Returns whether keylength is a valid key length.
void | SetKeyWithRounds (const byte *key, size_t length, int rounds)
| Sets or reset the key of this object.
void | SetKeyWithIV (const byte *key, size_t length, const byte *iv, size_t ivLength)
| Sets or reset the key of this object.
void | SetKeyWithIV (const byte *key, size_t length, const byte *iv)
| Sets or reset the key of this object.
virtual IV_Requirement | IVRequirement () const =0
| Minimal requirement for secure IVs.
bool | IsResynchronizable () const
| Determines if the object can be resynchronized.
bool | CanUseRandomIVs () const
| Determines if the object can use random IVs.
bool | CanUsePredictableIVs () const
| Determines if the object can use random but possibly predictable IVs.
bool | CanUseStructuredIVs () const
| Determines if the object can use structured IVs.
virtual unsigned int | IVSize () const
| Returns length of the IV accepted by this object.
unsigned int | DefaultIVLength () const
| Provides the default size of an IV.
virtual unsigned int | MinIVLength () const
| Provides the minimum size of an IV.
virtual unsigned int | MaxIVLength () const
| Provides the maximum size of an IV.
virtual void | GetNextIV (RandomNumberGenerator &rng, byte *iv)
| Retrieves a secure IV for the next message.
Public Member Functions inherited from HashTransformation
HashTransformation & | Ref ()
| Provides a reference to this object.
virtual byte * | CreateUpdateSpace (size_t &size)
| Request space which can be written into by the caller.
virtual void | Final (byte *digest)
| Computes the hash of the current message.
virtual unsigned int | DigestSize () const =0
| Provides the digest size of the hash.
unsigned int | TagSize () const
| Provides the tag size of the hash.
virtual unsigned int | BlockSize () const
| Provides the block size of the compression function.
virtual unsigned int | OptimalBlockSize () const
| Provides the input block size most efficient for this hash.
virtual unsigned int | OptimalDataAlignment () const
| Provides input and output data alignment for optimal performance.
virtual void | CalculateDigest (byte *digest, const byte *input, size_t length)
| Updates the hash with additional input and computes the hash of the current message.
virtual bool | Verify (const byte *digest)
| Verifies the hash of the current message.
virtual bool | VerifyDigest (const byte *digest, const byte *input, size_t length)
| Updates the hash with additional input and verifies the hash of the current message.
virtual void | CalculateTruncatedDigest (byte *digest, size_t digestSize, const byte *input, size_t length)
| Updates the hash with additional input and computes the hash of the current message.
virtual bool | TruncatedVerify (const byte *digest, size_t digestLength)
| Verifies the hash of the current message.
virtual bool | VerifyTruncatedDigest (const byte *digest, size_t digestLength, const byte *input, size_t length)
| Updates the hash with additional input and verifies the hash of the current message.
Public Member Functions inherited from Algorithm
| Algorithm (bool checkSelfTestStatus=true)
| Interface for all crypto algorithms.
Public Member Functions inherited from Clonable
virtual Clonable * | Clone () const
| Copies this object.
Public Member Functions inherited from StreamTransformation
StreamTransformation & | Ref ()
| Provides a reference to this object.
virtual unsigned int | MandatoryBlockSize () const
| Provides the mandatory block size of the cipher.
virtual unsigned int | OptimalBlockSize () const
| Provides the input block size most efficient for this cipher.
virtual unsigned int | GetOptimalBlockSizeUsed () const
| Provides the number of bytes used in the current block when processing at optimal block size.
virtual unsigned int | OptimalDataAlignment () const
| Provides input and output data alignment for optimal performance.
virtual size_t | ProcessLastBlock (byte *outString, size_t outLength, const byte *inString, size_t inLength)
| Encrypt or decrypt the last block of data.
virtual unsigned int | MinLastBlockSize () const
| Provides the size of the last block.
virtual bool | IsLastBlockSpecial () const
| Determines if the last block receives special processing.
void | ProcessString (byte *inoutString, size_t length)
| Encrypt or decrypt a string of bytes.
void | ProcessString (byte *outString, const byte *inString, size_t length)
| Encrypt or decrypt a string of bytes.
byte | ProcessByte (byte input)
| Encrypt or decrypt a byte.
virtual void | Seek (lword pos)
| Seek to an absolute position.
virtual bool | IsForwardTransformation () const =0
| Determines if the cipher is being operated in its forward direction.

## Additional Inherited Members

Public Types inherited from SimpleKeyingInterface
enum | IV_Requirement { UNIQUE_IV = 0 , RANDOM_IV , UNPREDICTABLE_RANDOM_IV , INTERNALLY_GENERATED_IV , NOT_RESYNCHRONIZABLE }
| Secure IVs requirements as enumerated values. More...

## Detailed Description

Base class for authenticated encryption modes of operation.

AuthenticatedSymmetricCipherBase() serves as a base implementation for one direction (encryption or decryption) of a stream cipher or block cipher mode with authentication.

Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the motivation for the API, like calling AAD a "header", can be found in Bellare, Rogaway and Wagner's The EAX Mode of Operation. The EAX paper suggested a basic API to help standardize AEAD schemes in software and promote adoption of the modes.

See also
  Authenticated Encryption on the Crypto++ wiki.

Since
  Crypto++ 5.6.0

Definition at line 40 of file authenc.h.

## Constructor & Destructor Documentation

## AuthenticatedSymmetricCipherBase()

AuthenticatedSymmetricCipherBase::AuthenticatedSymmetricCipherBase | ( |  | ) |

inline

Definition at line 43 of file authenc.h.

## Member Function Documentation

## IsRandomAccess()

bool AuthenticatedSymmetricCipherBase::IsRandomAccess | ( |  | ) | const

inline virtual

Determines whether the cipher supports random access.

Returns
  true if the cipher supports random access, false otherwise

Implements StreamTransformation.

Definition at line 47 of file authenc.h.

## IsSelfInverting()

bool AuthenticatedSymmetricCipherBase::IsSelfInverting | ( |  | ) | const

inline virtual

Determines whether the cipher is self-inverting.

Returns
  true if the cipher is self-inverting, false otherwise

IsSelfInverting determines whether this transformation is self-inverting (e.g. xor with a keystream).

Implements StreamTransformation.

Definition at line 48 of file authenc.h.

## SetKey()

void AuthenticatedSymmetricCipherBase::SetKey | ( | const byte * | key,
|  | size_t | length,
|  | const NameValuePairs & | params
| ) |  |

virtual

Sets or reset the key of this object.

Parameters

  key | the key to use when keying the object
  length | the size of the key, in bytes
  params | additional initialization parameters to configure this object

Reimplemented from SimpleKeyingInterface.

## Restart()

void AuthenticatedSymmetricCipherBase::Restart | ( |  | ) |

inline virtual

Restart the hash.

Discards the current state, and restart for a new message

Reimplemented from HashTransformation.

Definition at line 51 of file authenc.h.

## Resynchronize()

void AuthenticatedSymmetricCipherBase::Resynchronize | ( | const byte * | iv,
|  | int | ivLength = `-1`
| ) |  |

virtual

Resynchronize with an IV.

Parameters

  iv | the initialization vector
  ivLength | the size of the initialization vector, in bytes

Resynchronize() resynchronizes with an IV provided by the caller. `ivLength=-1` means use IVSize().

Exceptions

  NotImplemented() | if the object does not support resynchronization

Reimplemented from SimpleKeyingInterface.

## Update()

void AuthenticatedSymmetricCipherBase::Update | ( | const byte * | input,
|  | size_t | length
| ) |  |

virtual

Updates a hash with additional input.

Parameters

  input | the additional input as a buffer
  length | the size of the buffer, in bytes

Implements HashTransformation.

## ProcessData()

void AuthenticatedSymmetricCipherBase::ProcessData | ( | byte * | outString,
|  | const byte * | inString,
|  | size_t | length
| ) |  |

virtual

Encrypt or decrypt an array of bytes.

Parameters

  outString | the output byte buffer
  inString | the input byte buffer
  length | the size of the input and output byte buffers, in bytes

ProcessData is called with a string of bytes whose size depends on MandatoryBlockSize. Either `inString == outString`, or they must not overlap.

See also
  ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial

Implements StreamTransformation.

## TruncatedFinal()

void AuthenticatedSymmetricCipherBase::TruncatedFinal | ( | byte * | digest,
|  | size_t | digestSize
| ) |  |

virtual

Computes the hash of the current message.

Parameters

  digest | a pointer to the buffer to receive the hash
  digestSize | the size of the truncated digest, in bytes

TruncatedFinal() calls Final() and then copies digestSize bytes to digest. The hash is restarted the hash for the next message.

Precondition
  `COUNTOF(digest) <= DigestSize()` or `COUNTOF(digest) <= HASH::DIGESTSIZE` ensures the output byte buffer is a valid size.

Implements HashTransformation.

The documentation for this class was generated from the following file:

- authenc.h