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

poly1305.h
Go to the documentation of this file.
1 // poly1305.h - written and placed in the public domain by Jeffrey Walton and Jean-Pierre Munch
2 // Based on Andy Polyakov's Base-2^26 scalar multiplication implementation for OpenSSL.
3
4 /// \file poly1305.h
5 /// \brief Classes for Poly1305 message authentication code
6 /// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide
7 /// variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length
8 /// message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce.
9 /// \details Each message must use a unique security context, which means either the key or nonce
10 /// must be changed after each message. It can be accomplished in one of two ways. First, you
11 /// can create a new Poly1305 object with a key and nonce each time its needed.
12 /// <pre> SecByteBlock key(32), nonce(16);
13 /// prng.GenerateBlock(key, key.size());
14 /// prng.GenerateBlock(nonce, nonce.size());
15 ///
16 /// Poly1305<AES> poly1305(key, key.size(), nonce, nonce.size());
17 /// poly1305.Update(...);
18 /// poly1305.Final(...);</pre>
19 ///
20 /// \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce
21 /// for each message. The second and subsequent nonces can be generated directly using a
22 /// RandomNumberGenerator() derived class; or it can be generated using GetNextIV().
23 /// <pre> SecByteBlock key(32), nonce(16);
24 /// prng.GenerateBlock(key, key.size());
25 /// prng.GenerateBlock(nonce, nonce.size());
26 ///
27 /// // First message
28 /// Poly1305<AES> poly1305(key, key.size());
29 /// poly1305.Resynchronize(nonce);
30 /// poly1305.Update(...);
31 /// poly1305.Final(...);
32 ///
33 /// // Second message
34 /// poly1305.GetNextIV(prng, nonce);
35 /// poly1305.Resynchronize(nonce);
36 /// poly1305.Update(...);
37 /// poly1305.Final(...);
38 /// ...</pre>
39 /// \sa Daniel J. Bernstein <A HREF="http://cr.yp.to/mac/poly1305-20050329.pdf">The Poly1305-AES
40 /// Message-Authentication Code (20050329)</A> and Andy Polyakov <A
41 /// HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>
42 /// \since Crypto++ 6.0
43
44 #ifndef CRYPTOPP_POLY1305_H
45 #define CRYPTOPP_POLY1305_H
46
47 #include "cryptlib.h"
48 #include "seckey.h"
49 #include "secblock.h"
50 #include "argnames.h"
51 #include "algparam.h"
52
53 NAMESPACE_BEGIN(CryptoPP)
54
55 /// \brief Poly1305 message authentication code base class
56 /// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize
57 /// \since Crypto++ 6.0
58 template <class T>
59 class CRYPTOPP_NO_VTABLE Poly1305_Base : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 16>, public MessageAuthenticationCode
60 {
61 CRYPTOPP_COMPILE_ASSERT(T::DEFAULT_KEYLENGTH == 16);
62 CRYPTOPP_COMPILE_ASSERT(T::BLOCKSIZE == 16);
63
64 public:
65 static std::string StaticAlgorithmName() {return std::string("Poly1305(") + T::StaticAlgorithmName() + ")";}
66
67 CRYPTOPP_CONSTANT(DIGESTSIZE=T::BLOCKSIZE)
68 CRYPTOPP_CONSTANT(BLOCKSIZE=T::BLOCKSIZE)
69
70 Poly1305_Base() : m_idx(0), m_used(true) {}
71
72 void Resynchronize (const byte *iv, int ivLength=-1);
73 void GetNextIV (RandomNumberGenerator &rng, byte *iv);
74
75 void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params);
76 void Update(const byte *input, size_t length);
77 void TruncatedFinal(byte *mac, size_t size);
78 void Restart();
79
80 unsigned int BlockSize() const {return BLOCKSIZE;}
81 unsigned int DigestSize() const {return DIGESTSIZE;}
82
83 std::string AlgorithmProvider() const;
84
85 protected:
86 void HashBlocks(const byte *input, size_t length, word32 padbit);
87 void HashFinal(byte *mac, size_t length);
88
89 typename T::Encryption m_cipher;
90
91 // Accumulated hash, clamped r-key, and encrypted nonce
92 FixedSizeAlignedSecBlock<word32, 5> m_h;
93 FixedSizeAlignedSecBlock<word32, 4> m_r;
94 FixedSizeAlignedSecBlock<word32, 4> m_n;
95
96 // Accumulated message bytes and index
97 FixedSizeAlignedSecBlock<byte, BLOCKSIZE> m_acc, m_nk;
98 size_t m_idx;
99
100 // Track nonce reuse; assert in debug but continue
101 bool m_used;
102 };
103
104 /// \brief Poly1305 message authentication code
105 /// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize
106 /// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide
107 /// variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length
108 /// message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce.
109 /// \details Each message must use a unique security context, which means either the key or nonce
110 /// must be changed after each message. It can be accomplished in one of two ways. First, you
111 /// can create a new Poly1305 object with a key and nonce each time its needed.
112 /// <pre> SecByteBlock key(32), nonce(16);
113 /// prng.GenerateBlock(key, key.size());
114 /// prng.GenerateBlock(nonce, nonce.size());
115 ///
116 /// Poly1305<AES> poly1305(key, key.size(), nonce, nonce.size());
117 /// poly1305.Update(...);
118 /// poly1305.Final(...);</pre>
119 ///
120 /// \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce
121 /// for each message. The second and subsequent nonces can be generated directly using a
122 /// RandomNumberGenerator() derived class; or it can be generated using GetNextIV().
123 /// <pre> SecByteBlock key(32), nonce(16);
124 /// prng.GenerateBlock(key, key.size());
125 /// prng.GenerateBlock(nonce, nonce.size());
126 ///
127 /// // First message
128 /// Poly1305<AES> poly1305(key, key.size());
129 /// poly1305.Resynchronize(nonce);
130 /// poly1305.Update(...);
131 /// poly1305.Final(...);
132 ///
133 /// // Second message
134 /// poly1305.GetNextIV(prng, nonce);
135 /// poly1305.Resynchronize(nonce);
136 /// poly1305.Update(...);
137 /// poly1305.Final(...);
138 /// ...</pre>
139 /// \warning The Poly1305 class does not enforce a fresh nonce for each message. The source code
140 /// will assert in debug builds to alert of nonce reuse. No action is taken in release builds.
141 /// \sa Daniel J. Bernstein <A HREF="http://cr.yp.to/mac/poly1305-20050329.pdf">The Poly1305-AES
142 /// Message-Authentication Code (20050329)</A> and Andy Polyakov <A
143 /// HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>
144 /// \since Crypto++ 6.0
145 template <class T>
146 class Poly1305 : public MessageAuthenticationCodeFinal<Poly1305_Base<T> >
147 {
148 public:
149 CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=Poly1305_Base<T>::DEFAULT_KEYLENGTH)
150
151 /// \brief Construct a Poly1305
152 Poly1305() {}
153
154 /// \brief Construct a Poly1305
155 /// \param key a byte array used to key the cipher
156 /// \param keyLength the size of the byte array, in bytes
157 /// \param nonce a byte array used to key the cipher
158 /// \param nonceLength the size of the byte array, in bytes
159 /// \details key is the 32-byte key composed of the 16-byte AES key and the 16 additional key
160 /// bytes used for <tt>r</tt>.
161 /// \details Each message requires a unique security context. You can use GetNextIV() and
162 /// Resynchronize() to set a new nonce under a key for a message.
163 Poly1305(const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULLPTR, size_t nonceLength=0)
164 {this->SetKey(key, keyLength, MakeParameters(Name::IV(), ConstByteArrayParameter(nonce, nonceLength)));}
165 };
166
167 NAMESPACE_END
168
169 #endif // CRYPTOPP_POLY1305_H
ConstByteArrayParameter
Used to pass byte array input as part of a NameValuePairs object.
Definition: algparam.h:20
argnames.h
Standard names for retrieving values by name when working with NameValuePairs.
MessageAuthenticationCode
Interface for message authentication codes.
Definition: cryptlib.h:1264
Poly1305_Base
Poly1305 message authentication code base class.
Definition: poly1305.h:59
FixedKeyLength
Inherited by keyed algorithms with fixed key length.
Definition: seckey.h:124
algparam.h
Classes for working with NameValuePairs.
SimpleKeyingInterface::SetKey
virtual void SetKey(const byte *key, size_t length, const NameValuePairs &params=g_nullNameValuePairs)
Sets or reset the key of this object.
Definition: cryptlib.cpp:58
HashTransformation::TruncatedFinal
virtual void TruncatedFinal(byte *digest, size_t digestSize)=0
Computes the hash of the current message.
Poly1305_Base::BlockSize
unsigned int BlockSize() const
Provides the block size of the compression function.
Definition: poly1305.h:80
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
RandomNumberGenerator
Interface for random number generators.
Definition: cryptlib.h:1349
MessageAuthenticationCodeFinal
Provides class member functions to key a message authentication code.
Definition: seckey.h:370
Algorithm::AlgorithmProvider
virtual std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: cryptlib.h:608
secblock.h
Classes and functions for secure memory allocations.
MakeParameters
AlgorithmParameters MakeParameters(const char *name, const T &value, bool throwIfNotUsed=true)
Create an object that implements NameValuePairs.
Definition: algparam.h:502
HashTransformation::Restart
virtual void Restart()
Restart the hash.
Definition: cryptlib.h:1119
seckey.h
Classes and functions for implementing secret key algorithms.
SimpleKeyingInterface::Resynchronize
virtual void Resynchronize(const byte *iv, int ivLength=-1)
Resynchronize with an IV.
Definition: cryptlib.h:755
CRYPTOPP_COMPILE_ASSERT
#define CRYPTOPP_COMPILE_ASSERT(expr)
Compile time assertion.
Definition: misc.h:144
FixedSizeAlignedSecBlock< word32, 5 >
Poly1305
Poly1305 message authentication code.
Definition: poly1305.h:146
Name::IV
const char * IV()
ConstByteArrayParameter, also accepts const byte * for backwards compatibility.
Definition: argnames.h:21
Poly1305_Base::DigestSize
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: poly1305.h:81
Poly1305::Poly1305
Poly1305(const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULL, size_t nonceLength=0)
Construct a Poly1305.
Definition: poly1305.h:163
CryptoPP
Crypto++ library namespace.
SimpleKeyingInterface::GetNextIV
virtual void GetNextIV(RandomNumberGenerator &rng, byte *iv)
Retrieves a secure IV for the next message.
Definition: cryptlib.cpp:136
HashTransformation::Update
virtual void Update(const byte *input, size_t length)=0
Updates a hash with additional input.
NameValuePairs
Interface for retrieving values given their names.
Definition: cryptlib.h:293