poly1305.h File Reference

Classes for Poly1305 message authentication code. More...

#include "cryptlib.h"
#include "seckey.h"
#include "secblock.h"
#include "argnames.h"
#include "algparam.h"

Go to the source code of this file.

Classes
class	Poly1305_Base< T >
	Poly1305 message authentication code base class. More...
class	Poly1305< T >
	Poly1305 message authentication code. More...
class	Poly1305TLS_Base
	Poly1305-TLS message authentication code base class. More...

Functions
	DOCUMENTED_TYPEDEF (MessageAuthenticationCodeFinal< Poly1305TLS_Base >, Poly1305TLS)
	Poly1305-TLS message authentication code.

Detailed Description

Classes for Poly1305 message authentication code.

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.

Crypto++ also supplies the IETF's version of Poly1305. It is a slightly different algorithm than Bernstein's version.

See also

Daniel J. Bernstein The Poly1305-AES Message-Authentication Code (20050329), RFC 8439, ChaCha20 and Poly1305 for IETF Protocols and Andy Polyakov Poly1305 Revised

Since

Poly1305 since Crypto++ 6.0, Poly1305TLS since Crypto++ 8.1

Definition in file poly1305.h.

Function Documentation

DOCUMENTED_TYPEDEF()

DOCUMENTED_TYPEDEF	(	MessageAuthenticationCodeFinal< Poly1305TLS_Base >	,
		Poly1305TLS
	)

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