Security Scol plugin
Public Member Functions | List of all members
Poly1305< T > Class Template Reference

Poly1305 message authentication code. More...

#include <poly1305.h>

Inheritance diagram for Poly1305< T >:
MessageAuthenticationCodeFinal< Poly1305_Base< T > > ClonableImpl< DERIVED, BASE >

Public Member Functions

 CRYPTOPP_CONSTANT (DEFAULT_KEYLENGTH=Poly1305_Base< T >::DEFAULT_KEYLENGTH)
 
 Poly1305 ()
 Construct a Poly1305.
 
 Poly1305 (const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULLPTR, size_t nonceLength=0)
 Construct a Poly1305.
 
- Public Member Functions inherited from MessageAuthenticationCodeFinal< Poly1305_Base< T > >
 MessageAuthenticationCodeFinal ()
 Construct a default MessageAuthenticationCodeFinal.
 
 MessageAuthenticationCodeFinal (const byte *key)
 Construct a BlockCipherFinal.
 
 MessageAuthenticationCodeFinal (const byte *key, size_t length)
 Construct a BlockCipherFinal.
 
- Public Member Functions inherited from ClonableImpl< DERIVED, BASE >
ClonableClone () const
 Create a copy of this object.
 

Detailed Description

template<class T>
class Poly1305< T >

Poly1305 message authentication code.

Template Parameters
Tclass 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 = NULLPTR,
size_t  nonceLength = 0 
)
inline

Construct a Poly1305.

Parameters
keya byte array used to key the cipher
keyLengththe size of the byte array, in bytes
noncea byte array used to key the cipher
nonceLengththe 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: