Crypto++ 8.6 Free C++ class library of cryptographic schemes

Public Member Functions | Static Public Attributes | List of all members
Poly1305< T > Class Template Reference

Poly1305 message authentication code. More...

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. More...
Public Member Functions inherited from MessageAuthenticationCodeFinal< Poly1305_Base< T > >
| MessageAuthenticationCodeFinal ()
| Construct a default MessageAuthenticationCodeFinal. More...
| MessageAuthenticationCodeFinal (const byte *key)
| Construct a BlockCipherFinal. More...
| MessageAuthenticationCodeFinal (const byte *key, size_t length)
| Construct a BlockCipherFinal. More...
Public Member Functions inherited from ClonableImpl< DERIVED, BASE >
Clonable * | Clone () const
| Create a copy of this object. More...

## Static Public Attributes
static const int | DEFAULT_KEYLENGTH =Poly1305_Base<T>::DEFAULT_KEYLENGTH

## 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()

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.

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

- poly1305.h