include/cryptopp/poly1305.h

0001 // poly1305.h - written and placed in the public domain by Jeffrey Walton and Jean-Pierre Munch

0002 //              Based on Andy Polyakov's Base-2^26 scalar multiplication implementation.

0003 //              For more information, see https://www.openssl.org/~appro/cryptogams/.

0004
0005 // The library added Bernstein's Poly1305 classes at Crypto++ 6.0. The IETF

0006 // uses a slightly different implementation than Bernstein, and the IETF

0007 // classes were added at Crypto++ 8.1. We wanted to maintain ABI compatibility

0008 // at the 8.1 release so the original Poly1305 classes were not disturbed.

0009 // Instead new classes were added for IETF Poly1305. The back-end implementation

0010 // shares code as expected, however.

0011
0012 /// \file poly1305.h

0013 /// \brief Classes for Poly1305 message authentication code

0014 /// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide

0015 ///   variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length

0016 ///   message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce.

0017 /// \details Crypto++ also supplies the IETF's version of Poly1305. It is a slightly different

0018 ///   algorithm than Bernstein's version.

0019 /// \sa Daniel J. Bernstein <A HREF="http://cr.yp.to/mac/poly1305-20050329.pdf">The Poly1305-AES

0020 ///   Message-Authentication Code (20050329)</A>, <a href="http://tools.ietf.org/html/rfc8439">RFC

0021 ///   8439, ChaCha20 and Poly1305 for IETF Protocols</a> and Andy Polyakov <A

0022 ///   HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>

0023 /// \since Poly1305 since Crypto++ 6.0, Poly1305TLS since Crypto++ 8.1

0024
0025 #ifndef CRYPTOPP_POLY1305_H
0026 #define CRYPTOPP_POLY1305_H
0027
0028 #include "cryptlib.h"
0029 #include "seckey.h"
0030 #include "secblock.h"
0031 #include "argnames.h"
0032 #include "algparam.h"
0033
0034 NAMESPACE_BEGIN(CryptoPP)
0035
0036 ////////////////////////////// Bernstein Poly1305 //////////////////////////////

0037
0038 /// \brief Poly1305 message authentication code base class

0039 /// \tparam T BlockCipherDocumentation derived class with 16-byte key and 16-byte blocksize

0040 /// \details Poly1305_Base is the base class of Bernstein's Poly1305 algorithm.

0041 /// \since Crypto++ 6.0

0042 template <class T>
0043 class CRYPTOPP_NO_VTABLE Poly1305_Base : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 16>, public MessageAuthenticationCode
0044 {
0045     CRYPTOPP_COMPILE_ASSERT(T::DEFAULT_KEYLENGTH == 16);
0046     CRYPTOPP_COMPILE_ASSERT(T::BLOCKSIZE == 16);
0047
0048 public:
0049     static std::string StaticAlgorithmName() {return std::string("Poly1305(") + T::StaticAlgorithmName() + ")";}
0050
0051     CRYPTOPP_CONSTANT(DIGESTSIZE=T::BLOCKSIZE);
0052     CRYPTOPP_CONSTANT(BLOCKSIZE=T::BLOCKSIZE);
0053
0054     virtual ~Poly1305_Base() {}
0055     Poly1305_Base() : m_idx(0), m_used(true) {}
0056
0057     void Resynchronize (const byte *iv, int ivLength=-1);
0058     void GetNextIV (RandomNumberGenerator &rng, byte *iv);
0059
0060     void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params);
0061     void Update(const byte *input, size_t length);
0062     void TruncatedFinal(byte *mac, size_t size);
0063     void Restart();
0064
0065     unsigned int BlockSize() const {return BLOCKSIZE;}
0066     unsigned int DigestSize() const {return DIGESTSIZE;}
0067
0068     std::string AlgorithmProvider() const;
0069
0070 protected:
0071     // TODO: No longer needed. Remove at next major version bump

0072     void HashBlocks(const byte *input, size_t length, word32 padbit);
0073     void HashFinal(byte *mac, size_t length);
0074
0075     typename T::Encryption m_cipher;
0076
0077     // Accumulated hash, clamped r-key, and encrypted nonce

0078     FixedSizeAlignedSecBlock<word32, 5> m_h;
0079     FixedSizeAlignedSecBlock<word32, 4> m_r;
0080     FixedSizeAlignedSecBlock<word32, 4> m_n;
0081
0082     // Accumulated message bytes and index

0083     FixedSizeAlignedSecBlock<byte, BLOCKSIZE> m_acc, m_nk;
0084     size_t m_idx;
0085
0086     // Track nonce reuse; assert in debug but continue

0087     bool m_used;
0088 };
0089
0090 /// \brief Poly1305 message authentication code

0091 /// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize

0092 /// \details Poly1305-AES is a state-of-the-art message-authentication code suitable for a wide

0093 ///   variety of applications. Poly1305-AES computes a 16-byte authenticator of a variable-length

0094 ///   message, using a 16-byte AES key, a 16-byte additional key, and a 16-byte nonce.

0095 /// \details The key is 32 bytes and a concatenation <tt>key = {k,s}</tt>, where

0096 ///   <tt>k</tt> is the AES key and <tt>r</tt> is additional key that gets clamped.

0097 ///   The key is clamped internally so there is no need to perform the operation

0098 ///   before setting the key.

0099 /// \details Each message must have a unique security context, which means either the key or nonce

0100 ///   must be changed after each message. It can be accomplished in one of two ways. First, you

0101 ///   can create a new Poly1305 object each time its needed.

0102 ///   <pre>  SecByteBlock key(32), nonce(16);

0103 ///   prng.GenerateBlock(key, key.size());

0104 ///   prng.GenerateBlock(nonce, nonce.size());

0105 ///

0106 ///   Poly1305<AES> poly1305(key, key.size(), nonce, nonce.size());

0107 ///   poly1305.Update(...);

0108 ///   poly1305.Final(...);</pre>

0109 ///

0110 /// \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce

0111 ///   for each message. The second and subsequent nonces can be generated using GetNextIV().

0112 ///   <pre>  SecByteBlock key(32), nonce(16);

0113 ///   prng.GenerateBlock(key, key.size());

0114 ///   prng.GenerateBlock(nonce, nonce.size());

0115 ///

0116 ///   // First message

0117 ///   Poly1305<AES> poly1305(key, key.size());

0118 ///   poly1305.Resynchronize(nonce);

0119 ///   poly1305.Update(...);

0120 ///   poly1305.Final(...);

0121 ///

0122 ///   // Second message

0123 ///   poly1305.GetNextIV(prng, nonce);

0124 ///   poly1305.Resynchronize(nonce);

0125 ///   poly1305.Update(...);

0126 ///   poly1305.Final(...);

0127 ///   ...</pre>

0128 /// \warning Each message must have a unique security context. The Poly1305 class does not

0129 ///   enforce a fresh key or nonce for each message. The source code will assert in debug

0130 ///   builds to alert of nonce reuse. No action is taken in release builds.

0131 /// \sa Daniel J. Bernstein <A HREF="http://cr.yp.to/mac/poly1305-20050329.pdf">The Poly1305-AES

0132 ///   Message-Authentication Code (20050329)</A> and Andy Polyakov <A

0133 ///   HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>

0134 /// \since Crypto++ 6.0

0135 template <class T>
0136 class Poly1305 : public MessageAuthenticationCodeFinal<Poly1305_Base<T> >
0137 {
0138 public:
0139     CRYPTOPP_CONSTANT(DEFAULT_KEYLENGTH=Poly1305_Base<T>::DEFAULT_KEYLENGTH);
0140
0141     /// \brief Construct a Poly1305

0142     Poly1305() {}
0143
0144     /// \brief Construct a Poly1305

0145     /// \param key a byte array used to key the cipher

0146     /// \param keyLength the size of the byte array, in bytes

0147     /// \param nonce a byte array used to key the cipher

0148     /// \param nonceLength the size of the byte array, in bytes

0149     /// \details The key is 32 bytes and a concatenation <tt>key = {k,s}</tt>, where

0150     ///   <tt>k</tt> is the AES key and <tt>r</tt> is additional key that gets clamped.

0151     ///   The key is clamped internally so there is no need to perform the operation

0152     ///   before setting the key.

0153     /// \details Each message requires a unique security context. You can use GetNextIV()

0154     ///   and Resynchronize() to set a new nonce under a key for a message.

0155     Poly1305(const byte *key, size_t keyLength=DEFAULT_KEYLENGTH, const byte *nonce=NULLPTR, size_t nonceLength=0)
0156         {this->SetKey(key, keyLength, MakeParameters(Name::IV(), ConstByteArrayParameter(nonce, nonceLength)));}
0157 };
0158
0159 ////////////////////////////// IETF Poly1305 //////////////////////////////

0160
0161 /// \brief Poly1305-TLS message authentication code base class

0162 /// \details Poly1305TLS_Base is the base class of the IETF's Poly1305 algorithm.

0163 /// \since Crypto++ 8.1

0164 class Poly1305TLS_Base : public FixedKeyLength<32>, public MessageAuthenticationCode
0165 {
0166 public:
0167     static std::string StaticAlgorithmName() {return std::string("Poly1305TLS");}
0168     CRYPTOPP_CONSTANT(DIGESTSIZE=16);
0169     CRYPTOPP_CONSTANT(BLOCKSIZE=16);
0170
0171     virtual ~Poly1305TLS_Base() {}
0172     Poly1305TLS_Base() {}
0173
0174     void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params);
0175     void Update(const byte *input, size_t length);
0176     void TruncatedFinal(byte *mac, size_t size);
0177     void Restart();
0178
0179     unsigned int BlockSize() const {return BLOCKSIZE;}
0180     unsigned int DigestSize() const {return DIGESTSIZE;}
0181
0182 protected:
0183     // Accumulated hash, clamped r-key, and encrypted nonce

0184     FixedSizeAlignedSecBlock<word32, 5> m_h;
0185     FixedSizeAlignedSecBlock<word32, 4> m_r;
0186     FixedSizeAlignedSecBlock<word32, 4> m_n;
0187
0188     // Accumulated message bytes and index

0189     FixedSizeAlignedSecBlock<byte, BLOCKSIZE> m_acc;
0190     size_t m_idx;
0191 };
0192
0193 /// \brief Poly1305-TLS message authentication code

0194 /// \details This is the IETF's variant of Bernstein's Poly1305 from RFC 8439.

0195 ///   IETF Poly1305 is called Poly1305TLS in the Crypto++ library. It is

0196 ///   _slightly_ different from the Bernstein implementation. Poly1305-TLS

0197 ///   can be used for cipher suites

0198 ///   <tt>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>,

0199 ///   <tt>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</tt>, and

0200 ///   <tt>TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>.

0201 /// \details The key is 32 bytes and a concatenation <tt>key = {r,s}</tt>, where

0202 ///   <tt>r</tt> is additional key that gets clamped and <tt>s</tt> is the nonce.

0203 ///   The key is clamped internally so there is no need to perform the operation

0204 ///   before setting the key.

0205 /// \details Each message must have a unique security context, which means the key

0206 ///   must be changed after each message. It can be accomplished in one of two ways.

0207 ///   First, you can create a new Poly1305 object with a new key each time its needed.

0208 ///   <pre>  SecByteBlock key(32);

0209 ///   prng.GenerateBlock(key, key.size());

0210 ///

0211 ///   Poly1305TLS poly1305(key, key.size());

0212 ///   poly1305.Update(...);

0213 ///   poly1305.Final(...);</pre>

0214 ///

0215 /// \details Second, you can create a Poly1305 object, and use a new key for each

0216 ///   message. The keys can be generated directly using a RandomNumberGenerator()

0217 ///   derived class.

0218 ///   <pre>  SecByteBlock key(32);

0219 ///   prng.GenerateBlock(key, key.size());

0220 ///

0221 ///   // First message

0222 ///   Poly1305TLS poly1305(key, key.size());

0223 ///   poly1305.Update(...);

0224 ///   poly1305.Final(...);

0225 ///

0226 ///   // Second message

0227 ///   prng.GenerateBlock(key, key.size());

0228 ///   poly1305.SetKey(key, key.size());

0229 ///   poly1305.Update(...);

0230 ///   poly1305.Final(...);

0231 ///   ...</pre>

0232 /// \warning Each message must have a unique security context. The Poly1305-TLS class

0233 ///   does not enforce a fresh key or nonce for each message.

0234 /// \since Crypto++ 8.1

0235 /// \sa MessageAuthenticationCode(), <a href="http://tools.ietf.org/html/rfc8439">RFC

0236 ///   8439, ChaCha20 and Poly1305 for IETF Protocols</a>

0237 DOCUMENTED_TYPEDEF(MessageAuthenticationCodeFinal<Poly1305TLS_Base>, Poly1305TLS);
0238
0239 NAMESPACE_END
0240
0241 #endif  // CRYPTOPP_POLY1305_H