diff --git a/drbg.h b/drbg.h index 81694a94..8c3b146d 100644 --- a/drbg.h +++ b/drbg.h @@ -44,9 +44,9 @@ public: //! \param input the entropy to add to the generator //! \param length the size of the input buffer //! \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy - //! \details NIST instantiation and reseed requirements demand the generator is constructed with at least MINIMUM_ENTROPY entropy. - //! The byte array for input must meet NIST - //! SP 800-90C requirements. + //! \details NIST instantiation and reseed requirements demand the generator is constructed with at least MINIMUM_ENTROPY + //! entropy. The byte array for input must meet NIST + //! SP 800-90B or SP 800-90C requirements. virtual void IncorporateEntropy(const byte *input, size_t length)=0; //! \brief Update RNG state with additional unpredictable values @@ -57,8 +57,8 @@ public: //! \throws NIST_DRBG::Err if the generator is reseeded with insufficient entropy //! \details IncorporateEntropy() is an overload provided to match NIST requirements. NIST instantiation and //! reseed requirements demand the generator is constructed with at least MINIMUM_ENTROPY entropy. - //! The byte array for input must meet NIST - //! SP 800-90C requirements. + //! The byte array for entropy must meet NIST + //! SP 800-90B or SP 800-90C requirements. virtual void IncorporateEntropy(const byte *entropy, size_t entropyLength, const byte* additional, size_t additionaLength)=0; //! \brief Generate random array of bytes @@ -75,8 +75,8 @@ public: //! \param size the length of the buffer, in bytes //! \throws NIST_DRBG::Err if a reseed is required //! \throws NIST_DRBG::Err if the size exceeds MAXIMUM_BYTES_PER_REQUEST - //! \details GenerateBlock() is an overload provided to match NIST requirements. The byte array for additional input is optional. If present - //! the additional randomness is mixed before generating the output bytes. + //! \details GenerateBlock() is an overload provided to match NIST requirements. The byte array for additional + //! input is optional. If present the additional randomness is mixed before generating the output bytes. virtual void GenerateBlock(const byte* additional, size_t additionaLength, byte *output, size_t size)=0; //! \brief Provides the security strength @@ -90,28 +90,33 @@ public: //! used to maintain internal state of V and C. virtual unsigned int GetSeedLength() const=0; - //! \brief Provides the minimum entropy + //! \brief Provides the minimum entropy size //! \returns The minimum entropy size required by the generator, in bytes //! \details The equivalent class constant is MINIMUM_ENTROPY. All NIST DRBGs must be instaniated with at least //! MINIMUM_ENTROPY bytes of entropy. The bytes must meet NIST SP 800-90C requirements. + //! HREF="http://csrc.nist.gov/publications/PubsSPs.html">NIST SP 800-90B or SP 800-90C requirements. virtual unsigned int GetMinEntropy() const=0; - //! \brief Provides the maximum entropy + //! \brief Provides the maximum entropy size //! \returns The maximum entropy size that can be consumed by the generator, in bytes - //! \details The equivalent class constant is MAXIMUM_ENTROPY. MAXIMUM_ENTROPY has been reduced - //! from 235 to UINT_MAX to fit the C++ unsigned int datatype. + //! \details The equivalent class constant is MAXIMUM_ENTROPY. The bytes must meet NIST SP 800-90B or SP 800-90C requirements. + //! MAXIMUM_ENTROPY has been reduced from 235 to INT_MAX to fit the underlying C++ datatype. virtual unsigned int GetMaxEntropy() const=0; - //! \brief Provides the minimum nonce + //! \brief Provides the minimum nonce size //! \returns The minimum nonce size recommended for the generator, in bytes - //! \details The equivalent class constant is MINIMUM_NONCE. The nonce is optional but recommended + //! \details The equivalent class constant is MINIMUM_NONCE. If a nonce is not required then + //! MINIMUM_NONCE is 0. Hash_DRBG does not require a nonce, while HMAC_DRBG + //! and CTR_DRBG require a nonce. virtual unsigned int GetMinNonce() const=0; - //! \brief Provides the maximum nonce + //! \brief Provides the maximum nonce size //! \returns The maximum nonce that can be consumed by the generator, in bytes - //! \details The equivalent class constant is MAXIMUM_NONCE. The nonce is optional but recommended. - //! MAXIMUM_NONCE has been reduced from 235 to UINT_MAX to fit the C++ unsigned int datatype. + //! \details The equivalent class constant is MAXIMUM_NONCE. MAXIMUM_NONCE has been reduced from + //! 235 to INT_MAX to fit the underlying C++ datatype. If a nonce is not required then + //! MINIMUM_NONCE is 0. Hash_DRBG does not require a nonce, while HMAC_DRBG + //! and CTR_DRBG require a nonce. virtual unsigned int GetMaxNonce() const=0; //! \brief Provides the maximum size of a request to GenerateBlock @@ -121,7 +126,9 @@ public: //! \brief Provides the maximum number of requests before a reseed //! \returns The the maximum number of requests before a reseed, in bytes - //! \details The equivalent class constant is MAXIMUM_REQUESTS_BEFORE_RESEED + //! \details The equivalent class constant is MAXIMUM_REQUESTS_BEFORE_RESEED. + //! MAXIMUM_REQUESTS_BEFORE_RESEED has been reduced from 248 to INT_MAX + //! to fit the underlying C++ datatype. virtual unsigned int GetMaxRequestBeforeReseed() const=0; protected: @@ -141,10 +148,9 @@ protected: //! The remaining parameters are included in the class. The parameters and their values are listed //! in NIST SP 800-90A Rev. 1, Table 2: Definitions for Hash-Based DRBG Mechanisms (p.38). //! \details Some parameters have been reduce to fit C++ datatypes. For example, NIST allows upto 248 requests -//! before a reseed. However, Hash_DRBG limits it to UINT_MAX due to the limited data range of an unsigned int. +//! before a reseed. However, Hash_DRBG limits it to INT_MAX due to the limited data range of an int. //! \sa Recommendation -//! for Random Number Generation Using Deterministic Random Bit Generators, -//! Rev 1 (June 2015) +//! for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015) //! \since Crypto++ 5.7 template class Hash_DRBG : public NIST_DRBG @@ -156,12 +162,12 @@ public: CRYPTOPP_CONSTANT(MINIMUM_NONCE=0) CRYPTOPP_CONSTANT(MINIMUM_ADDITIONAL=0) CRYPTOPP_CONSTANT(MINIMUM_PERSONALIZATION=0) - CRYPTOPP_CONSTANT(MAXIMUM_ENTROPY=UINT_MAX) - CRYPTOPP_CONSTANT(MAXIMUM_NONCE=UINT_MAX) - CRYPTOPP_CONSTANT(MAXIMUM_ADDITIONAL=UINT_MAX) - CRYPTOPP_CONSTANT(MAXIMUM_PERSONALIZATION=UINT_MAX) + CRYPTOPP_CONSTANT(MAXIMUM_ENTROPY=INT_MAX) + CRYPTOPP_CONSTANT(MAXIMUM_NONCE=INT_MAX) + CRYPTOPP_CONSTANT(MAXIMUM_ADDITIONAL=INT_MAX) + CRYPTOPP_CONSTANT(MAXIMUM_PERSONALIZATION=INT_MAX) CRYPTOPP_CONSTANT(MAXIMUM_BYTES_PER_REQUEST=65536) - CRYPTOPP_CONSTANT(MAXIMUM_REQUESTS_BEFORE_RESEED=UINT_MAX) + CRYPTOPP_CONSTANT(MAXIMUM_REQUESTS_BEFORE_RESEED=INT_MAX) //! \brief Construct a Hash DRBG //! \param entropy the entropy to instantiate the generator @@ -169,14 +175,16 @@ public: //! \param nonce additional input to instantiate the generator //! \param nonceLength the size of the nonce buffer //! \param personalization additional input to instantiate the generator - //! \param personalizationLength the size of the additional input buffer + //! \param personalizationLength the size of the personalization buffer //! \throws NIST_DRBG::Err if the generator is instantiated with insufficient entropy - //! \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. The byte array for entropy must meet NIST - //! SP 800-90C requirements. - //! \details The nonce and personalization are optional byte arrays. If nonce is supplied, then it should include MINIMUM_NONCE bytes of entropy. + //! \details All NIST DRBGs must be instaniated with at least MINIMUM_ENTROPY bytes of entropy. + //! The byte array for entropy must meet NIST + //! SP 800-90B or SP 800-90C requirements. + //! \details The nonce and personalization are optional byte arrays. If nonce is supplied, + //! then it should be at least MINIMUM_NONCE bytes of entropy. //! \details An example of instantiating a SHA256 generator is shown below. //! The example provides more entropy than required for SHA256. The NonblockingRng meets the - //! requirements of NIST SP 800-90C. + //! requirements of NIST SP 800-90B or SP 800-90C. //! RDRAND() and RDSEED() generators would work as well. //! 
 	//!    SecByteBlock entropy(48), result(128);
@@ -196,11 +204,11 @@ public:
 	unsigned int GetSecurityStrength() const {return SECURITY_STRENGTH;}
 	unsigned int GetSeedLength() const {return SEED_LENGTH;}
 	unsigned int GetMinEntropy() const {return MINIMUM_ENTROPY;}
-	unsigned int GetMaxEntropy() const {return static_cast(MAXIMUM_ENTROPY);}
+	unsigned int GetMaxEntropy() const {return MAXIMUM_ENTROPY;}
 	unsigned int GetMinNonce() const {return MINIMUM_NONCE;}
-	unsigned int GetMaxNonce() const {return static_cast(MAXIMUM_NONCE);}
-	unsigned int GetMaxBytesPerRequest() const {return MAXIMUM_BYTES_PER_REQUEST;} // 2^16 bytes per request
-	unsigned int GetMaxRequestBeforeReseed() const {return static_cast(MAXIMUM_REQUESTS_BEFORE_RESEED);}
+	unsigned int GetMaxNonce() const {return MAXIMUM_NONCE;}
+	unsigned int GetMaxBytesPerRequest() const {return MAXIMUM_BYTES_PER_REQUEST;}
+	unsigned int GetMaxRequestBeforeReseed() const {return MAXIMUM_REQUESTS_BEFORE_RESEED;}
 
 	void IncorporateEntropy(const byte *input, size_t length)
 		{return DRBG_Reseed(input, length, NULL, 0);}
@@ -247,11 +255,11 @@ protected:
 	void DRBG_Instantiate(const byte* entropy, size_t entropyLength, const byte* nonce, size_t nonceLength,
 		const byte* personalization, size_t personalizationLength)
 	{
-		// 8.6.3: The entropy input shall have entropy that is equal to or greater than the security strength of the
-		//  instantiation. Additional entropy may be provided in the nonce or the optional personalization
-		//  string during instantiation, or in the additional input during reseeding and generation, but this is
-		//  not required and does not increase the “official” security strength of the DRBG instantiation that
-		//  is recorded in the internal state.
+		//  SP 800-90A, 8.6.3: The entropy input shall have entropy that is equal to or greater than the security
+		//  strength of the instantiation. Additional entropy may be provided in the nonce or the optional
+		//  personalization string during instantiation, or in the additional input during reseeding and generation,
+		//  but this is not required and does not increase the "official" security strength of the DRBG
+		//  instantiation that is recorded in the internal state.
 		CRYPTOPP_ASSERT(entropyLength >= MINIMUM_ENTROPY);
 		if (entropyLength < MINIMUM_ENTROPY)
 			throw NIST_DRBG::Err("Hash_DRBG", "Insufficient entropy during instantiate");
@@ -274,11 +282,11 @@ protected:
 	// 10.1.1.3 Reseeding a Hash_DRBG Instantiation (p.49)
 	void DRBG_Reseed(const byte* entropy, size_t entropyLength, const byte* additional, size_t additionaLength)
 	{
-		// 8.6.3: The entropy input shall have entropy that is equal to or greater than the security strength of the
-		//  instantiation. Additional entropy may be provided in the nonce or the optional personalization
-		//  string during instantiation, or in the additional input during reseeding and generation, but this is
-		//  not required and does not increase the “official” security strength of the DRBG instantiation that
-		//  is recorded in the internal state.
+		//  SP 800-90A, 8.6.3: The entropy input shall have entropy that is equal to or greater than the security
+		//  strength of the instantiation. Additional entropy may be provided in the nonce or the optional
+		//  personalization string during instantiation, or in the additional input during reseeding and generation,
+		//  but this is not required and does not increase the "official" security strength of the DRBG
+		//  instantiation that is recorded in the internal state..
 		CRYPTOPP_ASSERT(entropyLength >= MINIMUM_ENTROPY);
 		if (entropyLength < MINIMUM_ENTROPY)
 			throw NIST_DRBG::Err("Hash_DRBG", "Insufficient entropy during reseed");