Renamed ProcessBlocks → HashBlocks. Updated comments and documentation

poly1305.cpp

@@ -1,5 +1,5 @@
 // poly1305.cpp - written and placed in the public domain by Jeffrey Walton and Jean-Pierre Munch
-//                Based on Andy Polyakov's 32-bit OpenSSL implementation using scalar multiplication.
+//                Based on Andy Polyakov's Base-2^26 scalar multiplication implementation for OpenSSL.
 //                Copyright assigned to the Crypto++ project
 
 #include "pch.h"
@@ -61,7 +61,7 @@ void Poly1305_Base<T>::Update(const byte *input, size_t length)
 		{
 			// Process
 			memcpy_s(m_acc + num, BLOCKSIZE - num, input, rem);
-			ProcessBlocks(m_acc, BLOCKSIZE, 1);
+			HashBlocks(m_acc, BLOCKSIZE, 1);
 			input += rem;
 			length -= rem;
 		}
@@ -78,7 +78,7 @@ void Poly1305_Base<T>::Update(const byte *input, size_t length)
 	length -= rem;
 
 	if (length >= BLOCKSIZE) {
-		ProcessBlocks(input, length, 1);
+		HashBlocks(input, length, 1);
 		input += length;
 	}
 
@@ -89,7 +89,7 @@ void Poly1305_Base<T>::Update(const byte *input, size_t length)
 }
 
 template <class T>
-void Poly1305_Base<T>::ProcessBlocks(const byte *input, size_t length, word32 padbit)
+void Poly1305_Base<T>::HashBlocks(const byte *input, size_t length, word32 padbit)
 {
 	word32 r0, r1, r2, r3;
 	word32 s1, s2, s3;
@@ -174,10 +174,10 @@ void Poly1305_Base<T>::TruncatedFinal(byte *mac, size_t size)
 		m_acc[num++] = 1;   /* pad bit */
 		while (num < BLOCKSIZE)
 			m_acc[num++] = 0;
-		ProcessBlocks(m_acc, BLOCKSIZE, 0);
+		HashBlocks(m_acc, BLOCKSIZE, 0);
 	}
 
-	ProcessFinal(mac, size);
+	HashFinal(mac, size);
 
 	// Restart
 	m_used = true;
@@ -185,7 +185,7 @@ void Poly1305_Base<T>::TruncatedFinal(byte *mac, size_t size)
 }
 
 template <class T>
-void Poly1305_Base<T>::ProcessFinal(byte *mac, size_t size)
+void Poly1305_Base<T>::HashFinal(byte *mac, size_t size)
 {
 	word32 h0, h1, h2, h3, h4;
 	word32 g0, g1, g2, g3, g4;

poly1305.h

@@ -1,5 +1,5 @@
 // poly1305.h - written and placed in the public domain by Jeffrey Walton and Jean-Pierre Munch
-//              Based on Andy Polyakov's 32-bit OpenSSL implementation using scalar multiplication.
+//              Based on Andy Polyakov's Base-2^26 scalar multiplication implementation for OpenSSL.
 //              Copyright assigned to the Crypto++ project
 
 //! \file poly1305.h
@@ -18,8 +18,8 @@
 //!   poly1305.Update(...);
 //!   poly1305.Final(...);</pre>
 //!
-//! \details Second, you can create a Poly1305, reuse the key, and set a fresh nonce for
+//! \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce
-//!   each message. The second and subsequent nonces can be generated directly using a
+//!   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());
@@ -27,15 +27,16 @@
 //!
 //!   // First message
 //!   Poly1305<AES> poly1305(key, key.size());
-//!   poly1305.Resynchronize(nonce, nonce.size());
+//!   poly1305.Resynchronize(nonce);
 //!   poly1305.Update(...);
 //!   poly1305.Final(...);
 //!
-//!   // Third message
+//!   // Second message
 //!   poly1305.GetNextIV(prng, nonce);
-//!   poly1305.Resynchronize(nonce, nonce.size());
+//!   poly1305.Resynchronize(nonce);
 //!   poly1305.Update(...);
-//!   poly1305.Final(...);</pre>
+//!   poly1305.Final(...);
+//!   ...</pre>
 //! \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
 //!   HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>
@@ -82,8 +83,8 @@ public:
 	unsigned int DigestSize() const {return DIGESTSIZE;}
 
 protected:
-	void ProcessBlocks(const byte *input, size_t length, word32 padbit);
+	void HashBlocks(const byte *input, size_t length, word32 padbit);
-	void ProcessFinal(byte *mac, size_t length);
+	void HashFinal(byte *mac, size_t length);
 
 	CPP_TYPENAME T::Encryption m_cipher;
 
@@ -115,8 +116,8 @@ protected:
 //!   poly1305.Update(...);
 //!   poly1305.Final(...);</pre>
 //!
-//! \details Second, you can create a Poly1305, reuse the key, and set a fresh nonce for
+//! \details Second, you can create a Poly1305 object, reuse the key, and set a fresh nonce
-//!   each message. The second and subsequent nonces can be generated directly using a
+//!   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());
@@ -124,21 +125,18 @@ protected:
 //!
 //!   // First message
 //!   Poly1305<AES> poly1305(key, key.size());
-//!   poly1305.Resynchronize(nonce, nonce.size());
+//!   poly1305.Resynchronize(nonce);
 //!   poly1305.Update(...);
 //!   poly1305.Final(...);
 //!
 //!   // Second message
 //!   poly1305.GetNextIV(prng, nonce);
-//!   poly1305.Resynchronize(nonce, nonce.size());
+//!   poly1305.Resynchronize(nonce);
 //!   poly1305.Update(...);
 //!   poly1305.Final(...);
-//!
+//!   ...</pre>
-//!   // Third message
+//! \warn The Poly1305 class does not enforce a fresh nonce for each message. The source code
-//!   poly1305.GetNextIV(prng, nonce);
+//!   will assert in debug builds to alert of nonce reuse. No action is taken in releas builds.
-//!   poly1305.Resynchronize(nonce, nonce.size());
-//!   poly1305.Update(...);
-//!   poly1305.Final(...);</pre>
 //! \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
 //!   HREF="http://www.openssl.org/blog/blog/2016/02/15/poly1305-revised/">Poly1305 Revised</A>