From 6770a8dad4859e10fb58b54cf1b69137f4663e86 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton <noloader@gmail.com>
Date: Sun, 27 Jan 2019 05:45:05 -0500
Subject: [PATCH] Update documentation

---
 poly1305.cpp | 11 +++----
 poly1305.h   | 85 +++++++++++++++++++++++++++-------------------------
 2 files changed, 49 insertions(+), 47 deletions(-)

diff --git a/poly1305.cpp b/poly1305.cpp
index 15190543..fe1ae499 100644
--- a/poly1305.cpp
+++ b/poly1305.cpp
@@ -163,14 +163,14 @@ NAMESPACE_BEGIN(CryptoPP)
 
 ////////////////////////////// Bernstein Poly1305 //////////////////////////////
 
-// No longer needed. Remove at next major version bump
+// TODO: No longer needed. Remove at next major version bump
 template <class T>
 void Poly1305_Base<T>::HashBlocks(const byte *input, size_t length, word32 padbit) {
 	CRYPTOPP_UNUSED(input); CRYPTOPP_UNUSED(length); CRYPTOPP_UNUSED(padbit);
 	CRYPTOPP_ASSERT(0);
 }
 
-// No longer needed. Remove at next major version bump
+// TODO: No longer needed. Remove at next major version bump
 template <class T>
 void Poly1305_Base<T>::HashFinal(byte *mac, size_t length) {
 	CRYPTOPP_UNUSED(mac); CRYPTOPP_UNUSED(length);
@@ -188,7 +188,7 @@ void Poly1305_Base<T>::UncheckedSetKey(const byte *key, unsigned int length, con
 {
 	CRYPTOPP_ASSERT(key && length >= 32);
 
-	// key is {k,r} pair. k is AES key, r is 16 bytes
+	// key is {k,r} pair. k is AES key, r is the additional key that gets clamped
 	length = SaturatingSubtract(length, (unsigned)BLOCKSIZE);
 	m_cipher.SetKey(key, length);
 	key += length;
@@ -310,15 +310,12 @@ void Poly1305_Base<T>::Restart()
 
 ////////////////////////////// IETF Poly1305 //////////////////////////////
 
-//void Poly1305TLS_Base::Resynchronize (const byte *iv, int ivLength) {}
-//void Poly1305TLS_Base::GetNextIV (RandomNumberGenerator &rng, byte *iv) {}
-
 void Poly1305TLS_Base::UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params)
 {
 	CRYPTOPP_UNUSED(params);
 	CRYPTOPP_ASSERT(key && length >= 32);
 
-	// key is {r,s} pair. s is nonce, r is 16 bytes
+	// key is {r,s} pair. r is the additional key that gets clamped, s is the nonce.
 	m_r[0] = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, key +  0) & 0x0fffffff;
 	m_r[1] = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, key +  4) & 0x0ffffffc;
 	m_r[2] = GetWord<word32>(false, LITTLE_ENDIAN_ORDER, key +  8) & 0x0ffffffc;
diff --git a/poly1305.h b/poly1305.h
index 5d5e2120..7f651e53 100644
--- a/poly1305.h
+++ b/poly1305.h
@@ -6,38 +6,11 @@
 /// \details 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.
-/// \details Each message must use 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 with a key and nonce each time its needed.
-///   <pre>  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(...);</pre>
-///
-/// \details 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 directly using a
-///   RandomNumberGenerator() derived class; or it can be generated using GetNextIV().
-///   <pre>  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(...);
-///   ...</pre>
+/// \details Crypto++ also supplies the IETF's version of Poly1305. It is a slightly different
+///   algorithm than Bernstein's version.
 /// \sa Daniel J. Bernstein <A HREF="http://cr.yp.to/mac/poly1305-20050329.pdf">The Poly1305-AES
-///   Message-Authentication Code (20050329)</A> and Andy Polyakov <A
+///   Message-Authentication Code (20050329)</A>, <a href="http://tools.ietf.org/html/rfc8439">RFC
+///   8439, ChaCha20 and Poly1305 for IETF Protocols</a> and Andy Polyakov <A
 ///   HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>
 /// \since Crypto++ 6.0
 
@@ -56,6 +29,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 /// \brief Poly1305 message authentication code base class
 /// \tparam T class derived from BlockCipherDocumentation with 16-byte key and 16-byte blocksize
+/// \details Poly1305_Base is the base class of Bernstein's Poly1305 algorithm.
 /// \since Crypto++ 6.0
 template <class T>
 class CRYPTOPP_NO_VTABLE Poly1305_Base : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 16>, public MessageAuthenticationCode
@@ -110,6 +84,8 @@ protected:
 /// \details 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.
+/// \details The key is 32 bytes and a concatenation <tt>key = {k,s}</tt>, where
+///   <tt>k</tt> is the AES key and <tt>r</tt> is additional key that gets clamped.
 /// \details Each message must use 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 with a key and nonce each time its needed.
@@ -170,6 +146,9 @@ public:
 
 ////////////////////////////// IETF Poly1305 //////////////////////////////
 
+/// \brief Poly1305-TLS message authentication code base class
+/// \details Poly1305TLS_Base is the base class of the IETF's Poly1305 algorithm.
+/// \since Crypto++ 8.1
 class Poly1305TLS_Base : public FixedKeyLength<32>, public MessageAuthenticationCode
 {
 public:
@@ -180,9 +159,6 @@ public:
 	virtual ~Poly1305TLS_Base() {}
 	Poly1305TLS_Base() {}
 
-	//void Resynchronize (const byte *iv, int ivLength=-1);
-	//void GetNextIV (RandomNumberGenerator &rng, byte *iv);
-
 	void UncheckedSetKey(const byte *key, unsigned int length, const NameValuePairs &params);
 	void Update(const byte *input, size_t length);
 	void TruncatedFinal(byte *mac, size_t size);
@@ -191,8 +167,6 @@ public:
 	unsigned int BlockSize() const {return BLOCKSIZE;}
 	unsigned int DigestSize() const {return DIGESTSIZE;}
 
-	// std::string AlgorithmProvider() const;
-
 protected:
 	// Accumulated hash, clamped r-key, and encrypted nonce
 	FixedSizeAlignedSecBlock<word32, 5> m_h;
@@ -204,10 +178,41 @@ protected:
 	size_t m_idx;
 };
 
-/// \brief Poly1305 TLS message authentication code
-/// \tparam T HashTransformation class
-/// \details 160-bit MAC with 160-bit key
-/// \sa MessageAuthenticationCode()
+/// \brief Poly1305-TLS message authentication code
+/// \details Poly1305-TLS is the IETF's version of Poly1305. It is a slightly
+///   different algorithm than Bernstein's version.
+/// \details The key is 32 bytes and a concatenation <tt>key = {r,s}</tt>, where
+///   <tt>r</tt> is additional key that gets clamped and <tt>s</tt> is the nonce.
+/// \details Each message must use 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.
+///   <pre>  SecByteBlock key(32);
+///   prng.GenerateBlock(key, key.size());
+///
+///   Poly1305<AES> poly1305(key, key.size());
+///   poly1305.Update(...);
+///   poly1305.Final(...);</pre>
+///
+/// \details 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.
+///   <pre>  SecByteBlock key(32);
+///   prng.GenerateBlock(key, key.size());
+///
+///   // First message
+///   Poly1305<AES> poly1305(key, key.size());
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///
+///   // Second message
+///   prng.GenerateBlock(key, key.size());
+///   poly1305.SetKey(key, key.size());
+///   poly1305.Update(...);
+///   poly1305.Final(...);
+///   ...</pre>
+/// \since Crypto++ 8.1
+/// \sa MessageAuthenticationCode(), <a href="http://tools.ietf.org/html/rfc8439">RFC
+///   8439, ChaCha20 and Poly1305 for IETF Protocols</a>
 DOCUMENTED_TYPEDEF(MessageAuthenticationCodeFinal<Poly1305TLS_Base>, Poly1305TLS)
 
 NAMESPACE_END