Update documentation

1 files changed, 45 insertions, 40 deletions

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