Crypto++  5.6.5
Free C++ class library of cryptographic schemes
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
Hash_DRBG< HASH, STRENGTH, SEEDLENGTH > Class Template Reference

Hash_DRBG from SP 800-90A Rev 1 (June 2015) More...

+ Inheritance diagram for Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >:

Public Member Functions

 Hash_DRBG (const byte *entropy=NULL, size_t entropyLength=STRENGTH, const byte *nonce=NULL, size_t nonceLength=0, const byte *personalization=NULL, size_t personalizationLength=0)
 Construct a Hash DRBG. More...
 
unsigned int GetSecurityStrength () const
 Provides the security strength. More...
 
unsigned int GetSeedLength () const
 Provides the seed length. More...
 
unsigned int GetMinEntropy () const
 Provides the minimum entropy size. More...
 
unsigned int GetMaxEntropy () const
 Provides the maximum entropy size. More...
 
unsigned int GetMinNonce () const
 Provides the minimum nonce size. More...
 
unsigned int GetMaxNonce () const
 Provides the maximum nonce size. More...
 
unsigned int GetMaxBytesPerRequest () const
 Provides the maximum size of a request to GenerateBlock. More...
 
unsigned int GetMaxRequestBeforeReseed () const
 Provides the maximum number of requests before a reseed. More...
 
void IncorporateEntropy (const byte *input, size_t length)
 Update RNG state with additional unpredictable values. More...
 
void IncorporateEntropy (const byte *entropy, size_t entropyLength, const byte *additional, size_t additionaLength)
 Update RNG state with additional unpredictable values. More...
 
void GenerateBlock (byte *output, size_t size)
 Generate random array of bytes. More...
 
void GenerateBlock (const byte *additional, size_t additionaLength, byte *output, size_t size)
 Generate random array of bytes. More...
 
- Public Member Functions inherited from NIST_DRBG
virtual bool CanIncorporateEntropy () const
 Determines if a generator can accept additional entropy. More...
 
- Public Member Functions inherited from RandomNumberGenerator
virtual byte GenerateByte ()
 Generate new random byte and return it. More...
 
virtual unsigned int GenerateBit ()
 Generate new random bit and return it. More...
 
virtual word32 GenerateWord32 (word32 min=0, word32 max=0xffffffffUL)
 Generate a random 32 bit word in the range min to max, inclusive. More...
 
virtual void GenerateIntoBufferedTransformation (BufferedTransformation &target, const std::string &channel, lword length)
 Generate random bytes into a BufferedTransformation. More...
 
virtual void DiscardBytes (size_t n)
 Generate and discard n bytes. More...
 
template<class IT >
void Shuffle (IT begin, IT end)
 Randomly shuffle the specified array. More...
 
- Public Member Functions inherited from Algorithm
 Algorithm (bool checkSelfTestStatus=true)
 Interface for all crypto algorithms. More...
 
virtual std::string AlgorithmName () const
 Provides the name of this algorithm. More...
 
- Public Member Functions inherited from Clonable
virtual ClonableClone () const
 Copies this object. More...
 

Static Public Member Functions

static std::string StaticAlgorithmName ()
 

Static Public Attributes

static const int SECURITY_STRENGTH =STRENGTH
 
static const int SEED_LENGTH =SEEDLENGTH
 
static const int MINIMUM_ENTROPY =STRENGTH
 
static const int MINIMUM_NONCE =0
 
static const int MINIMUM_ADDITIONAL =0
 
static const int MINIMUM_PERSONALIZATION =0
 
static const int MAXIMUM_ENTROPY =INT_MAX
 
static const int MAXIMUM_NONCE =INT_MAX
 
static const int MAXIMUM_ADDITIONAL =INT_MAX
 
static const int MAXIMUM_PERSONALIZATION =INT_MAX
 
static const int MAXIMUM_BYTES_PER_REQUEST =65536
 
static const int MAXIMUM_REQUESTS_BEFORE_RESEED =INT_MAX
 

Detailed Description

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
class Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >

Hash_DRBG from SP 800-90A Rev 1 (June 2015)

Template Parameters
HASHNIST approved hash derived from HashTransformation
STRENGTHsecurity strength, in bytes
SEEDLENGTHseed length, in bytes

The NIST Hash DRBG is instantiated with a number of parameters. Two of the parameters, Security Strength and Seed Length, depend on the hash and are specified as template parameters. 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).

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 INT_MAX due to the limited data range of an int.

See also
Recommendation for Random Number Generation Using Deterministic Random Bit Generators, Rev 1 (June 2015)
Since
Crypto++ 6.0

Definition at line 165 of file drbg.h.

Constructor & Destructor Documentation

◆ Hash_DRBG()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::Hash_DRBG ( const byte *  entropy = NULL,
size_t  entropyLength = STRENGTH,
const byte *  nonce = NULL,
size_t  nonceLength = 0,
const byte *  personalization = NULL,
size_t  personalizationLength = 0 
)
inline

Construct a Hash DRBG.

Parameters
entropythe entropy to instantiate the generator
entropyLengththe size of the entropy buffer
nonceadditional input to instantiate the generator
nonceLengththe size of the nonce buffer
personalizationadditional input to instantiate the generator
personalizationLengththe size of the personalization buffer
Exceptions
NIST_DRBG::Errif the generator is instantiated with insufficient entropy

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.

The nonce and personalization are optional byte arrays. If nonce is supplied, then it should be at least MINIMUM_NONCE bytes of entropy.

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-90B or SP 800-90C. RDRAND() and RDSEED() generators would work as well.

   SecByteBlock entropy(48), result(128);
   NonblockingRng prng;
   RandomNumberSource rns(prng, entropy.size(), new ArraySink(entropy, entropy.size()));
   Hash_DRBG<SHA256, 128/8, 440/8> drbg(entropy, 32, entropy+32, 16);
   drbg.GenerateBlock(result, result.size());

Definition at line 208 of file drbg.h.

Member Function Documentation

◆ GetSecurityStrength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetSecurityStrength ( ) const
inlinevirtual

Provides the security strength.

Returns
The security strength of the generator, in bytes

The equivalent class constant is SECURITY_STRENGTH

Implements NIST_DRBG.

Definition at line 216 of file drbg.h.

◆ GetSeedLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetSeedLength ( ) const
inlinevirtual

Provides the seed length.

Returns
The seed size of the generator, in bytes

The equivalent class constant is SEED_LENGTH. The size is used to maintain internal state of V and C.

Implements NIST_DRBG.

Definition at line 217 of file drbg.h.

◆ GetMinEntropy()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMinEntropy ( ) const
inlinevirtual

Provides the minimum entropy size.

Returns
The minimum entropy size required by the generator, in bytes

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-90B or SP 800-90C requirements.

Implements NIST_DRBG.

Definition at line 218 of file drbg.h.

◆ GetMaxEntropy()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMaxEntropy ( ) const
inlinevirtual

Provides the maximum entropy size.

Returns
The maximum entropy size that can be consumed by the generator, in bytes

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.

Implements NIST_DRBG.

Definition at line 219 of file drbg.h.

◆ GetMinNonce()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMinNonce ( ) const
inlinevirtual

Provides the minimum nonce size.

Returns
The minimum nonce size recommended for the generator, in bytes

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.

Implements NIST_DRBG.

Definition at line 220 of file drbg.h.

◆ GetMaxNonce()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMaxNonce ( ) const
inlinevirtual

Provides the maximum nonce size.

Returns
The maximum nonce that can be consumed by the generator, in bytes

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.

Implements NIST_DRBG.

Definition at line 221 of file drbg.h.

◆ GetMaxBytesPerRequest()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMaxBytesPerRequest ( ) const
inlinevirtual

Provides the maximum size of a request to GenerateBlock.

Returns
The the maximum size of a request to GenerateBlock(), in bytes

The equivalent class constant is MAXIMUM_BYTES_PER_REQUEST

Implements NIST_DRBG.

Definition at line 222 of file drbg.h.

◆ GetMaxRequestBeforeReseed()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GetMaxRequestBeforeReseed ( ) const
inlinevirtual

Provides the maximum number of requests before a reseed.

Returns
The the maximum number of requests before a reseed, in bytes

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.

Implements NIST_DRBG.

Definition at line 223 of file drbg.h.

◆ IncorporateEntropy() [1/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::IncorporateEntropy ( const byte *  input,
size_t  length 
)
inlinevirtual

Update RNG state with additional unpredictable values.

Parameters
inputthe entropy to add to the generator
lengththe size of the input buffer
Exceptions
NIST_DRBG::Errif the generator is reseeded with insufficient entropy

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.

Implements NIST_DRBG.

Definition at line 225 of file drbg.h.

◆ IncorporateEntropy() [2/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::IncorporateEntropy ( const byte *  entropy,
size_t  entropyLength,
const byte *  additional,
size_t  additionaLength 
)
inlinevirtual

Update RNG state with additional unpredictable values.

Parameters
entropythe entropy to add to the generator
entropyLengththe size of the input buffer
additionaladditional input to add to the generator
additionaLengththe size of the additional input buffer
Exceptions
NIST_DRBG::Errif the generator is reseeded with insufficient entropy

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 entropy must meet NIST SP 800-90B or ! SP 800-90C requirements.

Implements NIST_DRBG.

Definition at line 228 of file drbg.h.

◆ GenerateBlock() [1/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GenerateBlock ( byte *  output,
size_t  size 
)
inlinevirtual

Generate random array of bytes.

Parameters
outputthe byte buffer
sizethe length of the buffer, in bytes
Exceptions
NIST_DRBG::Errif a reseed is required
NIST_DRBG::Errif the size exceeds MAXIMUM_BYTES_PER_REQUEST

Implements NIST_DRBG.

Definition at line 231 of file drbg.h.

◆ GenerateBlock() [2/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void Hash_DRBG< HASH, STRENGTH, SEEDLENGTH >::GenerateBlock ( const byte *  additional,
size_t  additionaLength,
byte *  output,
size_t  size 
)
inlinevirtual

Generate random array of bytes.

Parameters
additionaladditional input to add to the generator
additionaLengththe size of the additional input buffer
outputthe byte buffer
sizethe length of the buffer, in bytes
Exceptions
NIST_DRBG::Errif a reseed is required
NIST_DRBG::Errif the size exceeds MAXIMUM_BYTES_PER_REQUEST

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.

Implements NIST_DRBG.

Definition at line 234 of file drbg.h.


The documentation for this class was generated from the following file: