Poly1305TLS Class Reference

Poly1305-TLS message authentication code. More...

`#include <poly1305.h>`

Inheritance diagram for Poly1305TLS:

## 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...
Public Member Functions inherited from MessageAuthenticationCodeFinal< Poly1305TLS_Base >
| MessageAuthenticationCodeFinal ()
| Construct a default MessageAuthenticationCodeFinal.
Public Member Functions inherited from ClonableImpl< MessageAuthenticationCodeFinal< Poly1305TLS_Base >, MessageAuthenticationCodeImpl< Poly1305TLS_Base > >
Clonable * | Clone () const
| Create a copy of this object.
Public Member Functions inherited from AlgorithmImpl< SimpleKeyingInterfaceImpl< Poly1305TLS_Base, Poly1305TLS_Base >, Poly1305TLS_Base >
std::string | AlgorithmName () const
| The algorithm name.
Public Member Functions inherited from SimpleKeyingInterfaceImpl< Poly1305TLS_Base, Poly1305TLS_Base >
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 Poly1305TLS_Base
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.
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.
virtual void | Resynchronize (const byte *iv, int ivLength=-1)
| Resynchronize with 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.
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.
virtual std::string | AlgorithmProvider () const
| Retrieve the provider of this algorithm.
Static Public Member Functions inherited from AlgorithmImpl< SimpleKeyingInterfaceImpl< Poly1305TLS_Base, Poly1305TLS_Base >, Poly1305TLS_Base >
static std::string | StaticAlgorithmName ()
| The algorithm name.
Static Public Member Functions inherited from Poly1305TLS_Base
static std::string | StaticAlgorithmName ()
Static Public Member Functions inherited from FixedKeyLength< 32 >
static size_t | StaticGetValidKeyLength (size_t keylength)
| The default key length for the algorithm provided by a static function.
Static Public Attributes inherited from Poly1305TLS_Base
static const int | DIGESTSIZE =16
static const int | BLOCKSIZE =16
Static Public Attributes inherited from FixedKeyLength< 32 >
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.

## Detailed Description

Poly1305-TLS message authentication code.

This is the IETF's variant of Bernstein's Poly1305 from RFC 8439. IETF Poly1305 is called Poly1305TLS in the Crypto++ library. It is _slightly_ different from the Bernstein implementation. Poly1305-TLS can be used for cipher suites TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, and TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256.

The key is 32 bytes and a concatenation key = {r,s}, where r is additional key that gets clamped and s is the nonce. 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 the key must be changed after each message. It can be accomplished in one of two ways. First, you can create a new Poly1305 object with a new key each time its needed.

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

      Poly1305TLS poly1305(key, key.size());
      poly1305.Update(...);
      poly1305.Final(...);

Second, you can create a Poly1305 object, and use a new key for each message. The keys can be generated directly using a RandomNumberGenerator() derived class.

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

      // First message
      Poly1305TLS poly1305(key, key.size());
      poly1305.Update(...);
      poly1305.Final(...);

      // Second message
      prng.GenerateBlock(key, key.size());
      poly1305.SetKey(key, key.size());
      poly1305.Update(...);
      poly1305.Final(...);
      ...

Warning
  Each message must have a unique security context. The Poly1305-TLS class does not enforce a fresh key or nonce for each message.

Since
  Crypto++ 8.1

See also
  MessageAuthenticationCode(), RFC 8439, ChaCha20 and Poly1305 for IETF Protocols

Definition at line 237 of file poly1305.h.

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

- poly1305.h