Poly1305< T > Class Template Reference

Poly1305 message authentication code. More...

`#include <poly1305.h>`

Inheritance diagram for Poly1305< T >:

## Public Member Functions

| Poly1305 ()
| Construct a Poly1305.
| Poly1305 (const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULL, size_t nonceLength=0)
| Construct a Poly1305.
Public Member Functions inherited from MessageAuthenticationCodeFinal< Poly1305_Base< T > >
| MessageAuthenticationCodeFinal ()
| Construct a default MessageAuthenticationCodeFinal.
Public Member Functions inherited from ClonableImpl< MessageAuthenticationCodeFinal< Poly1305_Base< T > >, MessageAuthenticationCodeImpl< Poly1305_Base< T > > >
Clonable * | Clone () const
| Create a copy of this object.
Public Member Functions inherited from AlgorithmImpl< SimpleKeyingInterfaceImpl< Poly1305_Base< T >, Poly1305_Base< T > >, Poly1305_Base< T > >
std::string | AlgorithmName () const
| The algorithm name.
Public Member Functions inherited from SimpleKeyingInterfaceImpl< Poly1305_Base< T >, Poly1305_Base< T > >
size_t | MinKeyLength () const
| The minimum key length used by the algorithm.
size_t | MaxKeyLength () const
| The maximum key length used by the algorithm.
size_t | DefaultKeyLength () const
| The default key length used by the algorithm.
size_t | GetValidKeyLength (size_t keylength) const
| Provides a valid key length for the algorithm.
SimpleKeyingInterface::IV_Requirement | IVRequirement () const
| The default IV requirements for the algorithm.
unsigned int | IVSize () const
| The initialization vector length for the algorithm.
Public Member Functions inherited from Poly1305_Base< T >
void | Resynchronize (const byte *iv, int ivLength=-1)
| Resynchronize with an IV.
void | GetNextIV (RandomNumberGenerator &rng, byte *iv)
| Retrieves a secure IV for the next message.
void | UncheckedSetKey (const byte *key, unsigned int length, const NameValuePairs &params)
| Sets the key for this object without performing parameter validation.
void | Update (const byte *input, size_t length)
| Updates a hash with additional input.
void | TruncatedFinal (byte *mac, size_t size)
| Computes the hash of the current message.
void | Restart ()
| Restart the hash.
unsigned int | BlockSize () const
| Provides the block size of the compression function.
unsigned int | DigestSize () const
| Provides the digest size of the hash.
std::string | AlgorithmProvider () const
| Retrieve the provider of this algorithm.
Public Member Functions inherited from SimpleKeyingInterface
virtual bool | IsValidKeyLength (size_t keylength) const
| Returns whether keylength is a valid key length.
virtual void | SetKey (const byte *key, size_t length, const NameValuePairs &params=g_nullNameValuePairs)
| Sets or reset the key of this object.
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.
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.
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.
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.
unsigned int | TagSize () const
| Provides the tag size of the hash.
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.

## Static Public Attributes

static const int | DEFAULT_KEYLENGTH =Poly1305_Base<T>::DEFAULT_KEYLENGTH
Static Public Attributes inherited from Poly1305_Base< T >
static const int | DIGESTSIZE =T::BLOCKSIZE
static const int | BLOCKSIZE =T::BLOCKSIZE
Static Public Attributes inherited from FixedKeyLength< 32, SimpleKeyingInterface::UNIQUE_IV, 16 >
static const int | KEYLENGTH
| The default key length used by the algorithm provided as a constant.
static const int | MIN_KEYLENGTH
| The minimum key length used by the algorithm provided as a constant.
static const int | MAX_KEYLENGTH
| The maximum key length used by the algorithm provided as a constant.
static const int | DEFAULT_KEYLENGTH
| The default key length used by the algorithm provided as a constant.
static const int | IV_REQUIREMENT
| The default IV requirements for the algorithm provided as a constant.
static const int | IV_LENGTH
| The default IV length used by the algorithm provided as a constant.

## 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...
Static Public Member Functions inherited from AlgorithmImpl< SimpleKeyingInterfaceImpl< Poly1305_Base< T >, Poly1305_Base< T > >, Poly1305_Base< T > >
static std::string | StaticAlgorithmName ()
| The algorithm name.
Static Public Member Functions inherited from Poly1305_Base< T >
static std::string | StaticAlgorithmName ()
Static Public Member Functions inherited from FixedKeyLength< 32, SimpleKeyingInterface::UNIQUE_IV, 16 >
static size_t | StaticGetValidKeyLength (size_t keylength)
| The default key length for the algorithm provided by a static function.

## Detailed Description

template<class T>
class Poly1305< T >

Poly1305 message authentication code.

Template Parameters

  T | class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize

Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce.

The key is 32 bytes and a concatenation key = {k,s}, where k is the AES key and r is additional key that gets clamped. The key is clamped internally so there is no need to perform the operation before setting the key.

Each message must have a unique security context, which means either the key or nonce must be changed after each message. It can be accomplished in one of two ways. First, you can create a new Poly1305 object each time its needed.

      SecByteBlock key(32), nonce(16);
      prng.GenerateBlock(key, key.size());
      prng.GenerateBlock(nonce, nonce.size());

      Poly1305<AES> poly1305(key, key.size(), nonce, nonce.size());
      poly1305.Update(...);
      poly1305.Final(...);

Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce for each message. The second and subsequent nonces can be generated using GetNextIV().

      SecByteBlock key(32), nonce(16);
      prng.GenerateBlock(key, key.size());
      prng.GenerateBlock(nonce, nonce.size());

      // First message
      Poly1305<AES> poly1305(key, key.size());
      poly1305.Resynchronize(nonce);
      poly1305.Update(...);
      poly1305.Final(...);

      // Second message
      poly1305.GetNextIV(prng, nonce);
      poly1305.Resynchronize(nonce);
      poly1305.Update(...);
      poly1305.Final(...);
      ...

Warning
  Each message must have a unique security context. The Poly1305 class does not enforce a fresh key or nonce for each message. The source code will assert in debug builds to alert of nonce reuse. No action is taken in release builds.

See also
  Daniel J. Bernstein The Poly1305-AES Message-Authentication Code (20050329) and Andy Polyakov Poly1305 Revised

Since
  Crypto++ 6.0

Definition at line 136 of file poly1305.h.

## Constructor & Destructor Documentation

## Poly1305() [1/2]

template<class T>

Poly1305< T >::Poly1305 | ( |  | ) |

inline

Construct a Poly1305.

Definition at line 142 of file poly1305.h.

## Poly1305() [2/2]

template<class T>

Poly1305< T >::Poly1305 | ( | const byte * | key,
|  | size_t | keyLength = DEFAULT_KEYLENGTH,
|  | const byte * | nonce = NULL,
|  | size_t | nonceLength = 0 )

inline

Construct a Poly1305.

Parameters

  key | a byte array used to key the cipher
  keyLength | the size of the byte array, in bytes
  nonce | a byte array used to key the cipher
  nonceLength | the size of the byte array, in bytes

The key is 32 bytes and a concatenation key = {k,s}, where k is the AES key and r is additional key that gets clamped. The key is clamped internally so there is no need to perform the operation before setting the key.

Each message requires a unique security context. You can use GetNextIV() and Resynchronize() to set a new nonce under a key for a message.

Definition at line 155 of file poly1305.h.

## Member Data Documentation

## DEFAULT_KEYLENGTH

template<class T>

const int Poly1305< T >::DEFAULT_KEYLENGTH =Poly1305_Base<T>::DEFAULT_KEYLENGTH

static

Definition at line 139 of file poly1305.h.

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

- poly1305.h