From b7300a96ae9832a6f0369b4e7ec27221b950b849 Mon Sep 17 00:00:00 2001 From: Jeffrey Walton Date: Fri, 9 Sep 2016 04:45:20 -0400 Subject: [PATCH 1/4] Updated documentation --- keccak.h | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/keccak.h b/keccak.h index a5f4193a..4c8c3457 100644 --- a/keccak.h +++ b/keccak.h @@ -2,6 +2,13 @@ //! \file keccak.h //! \brief Classes for Keccak message digests +//! \details The Keccak classes use F1600 and XOF byte 0x80, which is effectively +//! the behavior specified by NIST at round three of the selection process. If you +//! desire FIPS 202 behavior, then use SHA3 classes. +//! \details Keccak will likely change in the future to accomodate extensibility of the +//! round function and the XOF functions. +//! \details Perform the following to specify a different digest size. It will use F1600 and 0x80. +//! 
Keccack_192 : public Keccack
 //! \sa Keccak
 
 #ifndef CRYPTOPP_KECCAK_H
@@ -14,6 +21,21 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class Keccak
 //! \brief Keccak message digest base class
+//! \details The Keccak classes use F1600 and XOF byte 0x80, which is effectively
+//!   the behavior specified by NIST at round three of the selection process. If you
+//!   desire FIPS 202 behavior, then use SHA3 classes.
+//! \details Keccak will likely change in the future to accomodate extensibility of the
+//!   round function and the XOF functions.
+//! \details Perform the following to specify a different digest size. The class will use F1600, 0x80,
+//!   and a new vaue for r() (which will be 200-2*24 = 152).
+//!   
Keccack_192 : public Keccack
+//!   {
+//!     public:
+//!       CRYPTOPP_CONSTANT(DIGESTSIZE = 24)
+//!       Keccack_192() : Keccack(DIGESTSIZE) {}
+//!   };
+//!   

+//!
 class Keccak : public HashTransformation
 {
 public:

From 1df4463c33e41caafc76c2739133c6069eda11e3 Mon Sep 17 00:00:00 2001
From: Jeffrey Walton 
Date: Fri, 9 Sep 2016 04:53:15 -0400
Subject: [PATCH 2/4] Whitespace cleanup

---
 keccak.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/keccak.h b/keccak.h
index 4c8c3457..4d75b5e5 100644
--- a/keccak.h
+++ b/keccak.h
@@ -28,7 +28,7 @@ NAMESPACE_BEGIN(CryptoPP)
 //!   round function and the XOF functions.
 //! \details Perform the following to specify a different digest size. The class will use F1600, 0x80,
 //!   and a new vaue for r() (which will be 200-2*24 = 152).
-//!   
Keccack_192 : public Keccack
+//!   
  Keccack_192 : public Keccack
 //!   {
 //!     public:
 //!       CRYPTOPP_CONSTANT(DIGESTSIZE = 24)

From e4e01a6af3964750d032153d7f1c96fc9eee107c Mon Sep 17 00:00:00 2001
From: Jeffrey Walton 
Date: Fri, 9 Sep 2016 05:04:36 -0400
Subject: [PATCH 3/4] Updated documentation

---
 keccak.h | 8 +++++---
 sha3.h   | 8 ++++++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/keccak.h b/keccak.h
index 4d75b5e5..41302c79 100644
--- a/keccak.h
+++ b/keccak.h
@@ -7,8 +7,6 @@
 //!   desire FIPS 202 behavior, then use SHA3 classes.
 //! \details Keccak will likely change in the future to accomodate extensibility of the
 //!   round function and the XOF functions.
-//! \details Perform the following to specify a different digest size. It will use F1600 and 0x80.
-//! 
Keccack_192 : public Keccack
 //! \sa Keccak
 
 #ifndef CRYPTOPP_KECCAK_H
@@ -24,6 +22,9 @@ NAMESPACE_BEGIN(CryptoPP)
 //! \details The Keccak classes use F1600 and XOF byte 0x80, which is effectively
 //!   the behavior specified by NIST at round three of the selection process. If you
 //!   desire FIPS 202 behavior, then use SHA3 classes.
+//! \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512.
+//!   Library users should instantiate a derived class, and only use Keccak
+//!   as a base class reference or pointer.
 //! \details Keccak will likely change in the future to accomodate extensibility of the
 //!   round function and the XOF functions.
 //! \details Perform the following to specify a different digest size. The class will use F1600, 0x80,
@@ -36,13 +37,14 @@ NAMESPACE_BEGIN(CryptoPP)
 //!   };
 //!   

 //!
+//! \sa SHA3, Keccak_224, Keccak_256, Keccak_384 and Keccak_512.
 class Keccak : public HashTransformation
 {
 public:
 	//! \brief Construct a Keccak
 	//! \param digestSize the digest size, in bytes
 	//! \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512.
-	//!   Library users should construct a derived class instead, and only use Keccak
+	//!   Library users should instantiate a derived class, and only use Keccak
 	//!   as a base class reference or pointer.
 	Keccak(unsigned int digestSize) : m_digestSize(digestSize) {Restart();}
 	unsigned int DigestSize() const {return m_digestSize;}
diff --git a/sha3.h b/sha3.h
index ed3a03b8..0337fbac 100644
--- a/sha3.h
+++ b/sha3.h
@@ -3,7 +3,7 @@
 //! \file sha3.h
 //! \brief Classes for SHA-3 message digests
 //! \details The Crypto++ SHA-3 conforms to FIPS 202 version of SHA-3.
-//!   Previous behavior is available in Keccak classes.
+//!   Previous behavior is available in SHA3 classes.
 //! \sa SHA-3,
 //!   SHA-3 STANDARD (FIPS 202).
 
@@ -17,13 +17,17 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class SHA3
 //! \brief SHA3 message digest base class
+	//! \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512.
+	//!   Library users should instantiate a derived class, and only use SHA3
+	//!   as a base class reference or pointer.
+	//! \sa Keccak, SHA3_224, SHA3_256, SHA3_384 and SHA3_512.
 class SHA3 : public HashTransformation
 {
 public:
 	//! \brief Construct a SHA3
 	//! \param digestSize the digest size, in bytes
 	//! \details SHA3 is the base class for SHA3_224, SHA3_256, SHA3_384 and SHA3_512.
-	//!   Library users should construct a derived class instead, and only use SHA3
+	//!   Library users should instantiate a derived class, and only use SHA3
 	//!   as a base class reference or pointer.
 	SHA3(unsigned int digestSize) : m_digestSize(digestSize) {Restart();}
 	unsigned int DigestSize() const {return m_digestSize;}

From 36d769e9077b0e891440a7d32f14a84f80909aab Mon Sep 17 00:00:00 2001
From: Jeffrey Walton 
Date: Fri, 9 Sep 2016 05:19:29 -0400
Subject: [PATCH 4/4] Updated documentation

---
 blake2.h  | 7 +++++++
 chacha.h  | 6 ++++++
 fhmqv.h   | 3 +++
 hkdf.h    | 2 ++
 hmqv.h    | 3 +++
 integer.h | 7 +++++--
 keccak.h  | 7 +++++++
 sha3.h    | 6 ++++++
 8 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/blake2.h b/blake2.h
index ef7819df..5c1655da 100644
--- a/blake2.h
+++ b/blake2.h
@@ -13,6 +13,7 @@
 //! \details The library provides specialized SSE2, SSE4 and NEON version of the BLAKE2 compression
 //!   function. For best results under ARM NEON, specify both an architecture and cpu. For example:
 //!   
CXXFLAGS="-DNDEBUG -march=armv8-a+crc -mcpu=cortex-a53 ..."

+//! \since Crypto++ 5.6.4
 
 #ifndef CRYPTOPP_BLAKE2_H
 #define CRYPTOPP_BLAKE2_H
@@ -26,6 +27,7 @@ NAMESPACE_BEGIN(CryptoPP)
 //! \class BLAKE2_Info
 //! \brief BLAKE2 hash information
 //! \tparam T_64bit flag indicating 64-bit
+//! \since Crypto++ 5.6.4
 template 
 struct BLAKE2_Info : public VariableKeyLength<(T_64bit ? 64 : 32),0,(T_64bit ? 64 : 32),1,SimpleKeyingInterface::NOT_RESYNCHRONIZABLE>
 {
@@ -47,6 +49,7 @@ struct BLAKE2_Info : public VariableKeyLength<(T_64bit ? 64 : 32),0,(T_64bit ? 6
 //! \tparam T_64bit flag indicating 64-bit
 //! \details BLAKE2b uses BLAKE2_ParameterBlock, while BLAKE2s
 //!   uses BLAKE2_ParameterBlock.
+//! \since Crypto++ 5.6.4
 template 
 struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock
 {
@@ -128,6 +131,7 @@ struct CRYPTOPP_NO_VTABLE BLAKE2_ParameterBlock
 //! \tparam T_64bit flag indicating 64-bit
 //! \details BLAKE2b uses BLAKE2_State, while BLAKE2s
 //!   uses BLAKE2_State.
+//! \since Crypto++ 5.6.4
 template 
 struct CRYPTOPP_NO_VTABLE BLAKE2_State
 {
@@ -153,6 +157,7 @@ struct CRYPTOPP_NO_VTABLE BLAKE2_State
 //! \tparam T_64bit flag indicating 64-bit
 //! \details BLAKE2b uses BLAKE2_Base, while BLAKE2s
 //!   uses BLAKE2_Base.
+//! \since Crypto++ 5.6.4
 template 
 class BLAKE2_Base : public SimpleKeyingInterfaceImpl >
 {
@@ -240,6 +245,7 @@ private:
 //!   method that accepts a ParameterBlock does not allow you to change it.
 //! \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's
 //!   BLAKE2: simpler, smaller, fast as MD5 (2013.01.29).
+//! \since Crypto++ 5.6.4
 class BLAKE2b : public BLAKE2_Base
 {
 public:
@@ -275,6 +281,7 @@ public:
 //!   method that accepts a ParameterBlock does not allow you to change it.
 //! \sa Aumasson, Neves, Wilcox-O'Hearn and Winnerlein's
 //!   BLAKE2: simpler, smaller, fast as MD5 (2013.01.29).
+//! \since Crypto++ 5.6.4
 class BLAKE2s : public BLAKE2_Base
 {
 public:
diff --git a/chacha.h b/chacha.h
index 462003d9..b1099a35 100644
--- a/chacha.h
+++ b/chacha.h
@@ -5,6 +5,7 @@
 
 //! \file chacha.h
 //! \brief Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers
+//! \since Crypto++ 5.6.4
 
 #ifndef CRYPTOPP_CHACHA_H
 #define CRYPTOPP_CHACHA_H
@@ -16,6 +17,7 @@ NAMESPACE_BEGIN(CryptoPP)
 
 //! \class ChaCha_Info
 //! \brief ChaCha stream cipher information
+//! \since Crypto++ 5.6.4
 template 
 struct ChaCha_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterface::UNIQUE_IV, 8>, public FixedRounds
 {
@@ -26,6 +28,7 @@ struct ChaCha_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterf
 
 //! \class ChaCha_Policy
 //! \brief ChaCha stream cipher implementation
+//! \since Crypto++ 5.6.4
 template 
 class CRYPTOPP_NO_VTABLE ChaCha_Policy : public AdditiveCipherConcretePolicy
 {
@@ -46,6 +49,7 @@ protected:
 //! \class ChaCha8
 //! \brief ChaCha8 stream cipher
 //! \sa ChaCha, a variant of Salsa20 (2008.01.28).
+//! \since Crypto++ 5.6.4
 struct ChaCha8 : public ChaCha_Info<8>, public SymmetricCipherDocumentation
 {
 	typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<8> > Encryption;
@@ -55,6 +59,7 @@ struct ChaCha8 : public ChaCha_Info<8>, public SymmetricCipherDocumentation
 //! \class ChaCha12
 //! \brief ChaCha12 stream cipher
 //! \sa ChaCha, a variant of Salsa20 (2008.01.28).
+//! \since Crypto++ 5.6.4
 struct ChaCha12 : public ChaCha_Info<12>, public SymmetricCipherDocumentation
 {
 	typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<12> > Encryption;
@@ -64,6 +69,7 @@ struct ChaCha12 : public ChaCha_Info<12>, public SymmetricCipherDocumentation
 //! \class ChaCha20
 //! \brief ChaCha20 stream cipher
 //! \sa ChaCha, a variant of Salsa20 (2008.01.28).
+//! \since Crypto++ 5.6.4
 struct ChaCha20 : public ChaCha_Info<20>, public SymmetricCipherDocumentation
 {
 	typedef SymmetricCipherFinal, AdditiveCipherTemplate<> >, ChaCha_Info<20> > Encryption;
diff --git a/fhmqv.h b/fhmqv.h
index 6a527b70..0e9a317b 100644
--- a/fhmqv.h
+++ b/fhmqv.h
@@ -6,6 +6,7 @@
 
 //! \file fhmqv.h
 //! \brief Classes for Fully Hashed Menezes-Qu-Vanstone key agreement in GF(p)
+//! \since Crypto++ 5.6.4
 
 #include "gfpcrypt.h"
 #include "algebra.h"
@@ -18,6 +19,7 @@ NAMESPACE_BEGIN(CryptoPP)
 //!   A Secure and Efficient Authenticated Diffie-Hellman Protocol.
 //!   Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C.
 //! \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain
+//! \since Crypto++ 5.6.4
 template 
 class FHMQV_Domain : public AuthenticatedKeyAgreementDomain
 {
@@ -294,6 +296,7 @@ private:
 //!   A Secure and Efficient Authenticated Diffie-Hellman Protocol.
 //!   Note: this is FHMQV, Protocol 5, from page 11; and not FHMQV-C.
 //! \sa FHMQV, MQV_Domain, HMQV_Domain, AuthenticatedKeyAgreementDomain
+//! \since Crypto++ 5.6.4
 typedef FHMQV_Domain FHMQV;
 
 NAMESPACE_END
diff --git a/hkdf.h b/hkdf.h
index 57c456b1..447d15dc 100644
--- a/hkdf.h
+++ b/hkdf.h
@@ -2,6 +2,7 @@
 
 //! \file hkdf.h
 //! \brief Classes for HKDF from RFC 5869
+//! \since Crypto++ 5.6.3
 
 #ifndef CRYPTOPP_HASH_KEY_DERIVATION_FUNCTION_H
 #define CRYPTOPP_HASH_KEY_DERIVATION_FUNCTION_H
@@ -30,6 +31,7 @@ public:
 //! \tparam T HashTransformation class
 //! \sa Cryptographic Extraction and Key Derivation: The HKDF Scheme
 //!   and HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
+//! \since Crypto++ 5.6.3
 template 
 class HKDF : public KeyDerivationFunction
 {
diff --git a/hmqv.h b/hmqv.h
index 697ae343..2aa4058b 100644
--- a/hmqv.h
+++ b/hmqv.h
@@ -6,6 +6,7 @@
 
 //! \file hmqv.h
 //! \brief Classes for Hashed Menezes-Qu-Vanstone key agreement in GF(p)
+//! \since Crypto++ 5.6.4
 
 #include "gfpcrypt.h"
 #include "algebra.h"
@@ -17,6 +18,7 @@ NAMESPACE_BEGIN(CryptoPP)
 //! \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance
 //!   Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided.
 //! \sa MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain
+//! \since Crypto++ 5.6.4
 template 
 class HMQV_Domain: public AuthenticatedKeyAgreementDomain
 {
@@ -302,6 +304,7 @@ private:
 //! \details This implementation follows Hugo Krawczyk's HMQV: A High-Performance
 //!   Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided.
 //! \sa HMQV, MQV_Domain, FHMQV_Domain, AuthenticatedKeyAgreementDomain
+//! \since Crypto++ 5.6.4
 typedef HMQV_Domain HMQV;
 
 NAMESPACE_END
diff --git a/integer.h b/integer.h
index ffd8bce6..66267c5a 100644
--- a/integer.h
+++ b/integer.h
@@ -1,8 +1,11 @@
+// integer.h - written and placed in the public domain by Wei Dai
+
+//! \file integer.h
+//! \brief High performance arbitrary size integer class
+
 #ifndef CRYPTOPP_INTEGER_H
 #define CRYPTOPP_INTEGER_H
 
-/** \file */
-
 #include "cryptlib.h"
 #include "secblock.h"
 #include "stdcpp.h"
diff --git a/keccak.h b/keccak.h
index 41302c79..9103963d 100644
--- a/keccak.h
+++ b/keccak.h
@@ -8,6 +8,7 @@
 //! \details Keccak will likely change in the future to accomodate extensibility of the
 //!   round function and the XOF functions.
 //! \sa Keccak
+//! \since Crypto++ 5.6.4
 
 #ifndef CRYPTOPP_KECCAK_H
 #define CRYPTOPP_KECCAK_H
@@ -38,6 +39,7 @@ NAMESPACE_BEGIN(CryptoPP)
 //!   

 //!
 //! \sa SHA3, Keccak_224, Keccak_256, Keccak_384 and Keccak_512.
+//! \since Crypto++ 5.6.4
 class Keccak : public HashTransformation
 {
 public:
@@ -46,6 +48,7 @@ public:
 	//! \details Keccak is the base class for Keccak_224, Keccak_256, Keccak_384 and Keccak_512.
 	//!   Library users should instantiate a derived class, and only use Keccak
 	//!   as a base class reference or pointer.
+	//! \since Crypto++ 5.6.4
 	Keccak(unsigned int digestSize) : m_digestSize(digestSize) {Restart();}
 	unsigned int DigestSize() const {return m_digestSize;}
 	std::string AlgorithmName() const {return "Keccak-" + IntToString(m_digestSize*8);}
@@ -64,6 +67,7 @@ protected:
 
 //! \class Keccak_224
 //! \brief Keccak-224 message digest
+//! \since Crypto++ 5.6.4
 class Keccak_224 : public Keccak
 {
 public:
@@ -76,6 +80,7 @@ public:
 
 //! \class Keccak_256
 //! \brief Keccak-256 message digest
+//! \since Crypto++ 5.6.4
 class Keccak_256 : public Keccak
 {
 public:
@@ -88,6 +93,7 @@ public:
 
 //! \class Keccak_384
 //! \brief Keccak-384 message digest
+//! \since Crypto++ 5.6.4
 class Keccak_384 : public Keccak
 {
 public:
@@ -100,6 +106,7 @@ public:
 
 //! \class Keccak_512
 //! \brief Keccak-512 message digest
+//! \since Crypto++ 5.6.4
 class Keccak_512 : public Keccak
 {
 public:
diff --git a/sha3.h b/sha3.h
index 0337fbac..2f111845 100644
--- a/sha3.h
+++ b/sha3.h
@@ -6,6 +6,7 @@
 //!   Previous behavior is available in SHA3 classes.
 //! \sa SHA-3,
 //!   SHA-3 STANDARD (FIPS 202).
+//! \since Crypto++ 5.6.2
 
 #ifndef CRYPTOPP_SHA3_H
 #define CRYPTOPP_SHA3_H
@@ -21,6 +22,7 @@ NAMESPACE_BEGIN(CryptoPP)
 	//!   Library users should instantiate a derived class, and only use SHA3
 	//!   as a base class reference or pointer.
 	//! \sa Keccak, SHA3_224, SHA3_256, SHA3_384 and SHA3_512.
+	//! \since Crypto++ 5.6.2
 class SHA3 : public HashTransformation
 {
 public:
@@ -47,6 +49,7 @@ protected:
 
 //! \class SHA3_224
 //! \brief SHA3-224 message digest
+//! \since Crypto++ 5.6.2
 class SHA3_224 : public SHA3
 {
 public:
@@ -59,6 +62,7 @@ public:
 
 //! \class SHA3_256
 //! \brief SHA3-256 message digest
+//! \since Crypto++ 5.6.2
 class SHA3_256 : public SHA3
 {
 public:
@@ -71,6 +75,7 @@ public:
 
 //! \class SHA3_384
 //! \brief SHA3-384 message digest
+//! \since Crypto++ 5.6.2
 class SHA3_384 : public SHA3
 {
 public:
@@ -83,6 +88,7 @@ public:
 
 //! \class SHA3_512
 //! \brief SHA3-512 message digest
+//! \since Crypto++ 5.6.2
 class SHA3_512 : public SHA3
 {
 public: