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

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

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

Public Member Functions

 HMAC_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 HMAC DRBG. More...
 
unsigned int SecurityStrength () const
 Provides the security strength. More...
 
unsigned int SeedLength () const
 Provides the seed length. More...
 
unsigned int MinEntropyLength () const
 Provides the minimum entropy size. More...
 
unsigned int MaxEntropyLength () const
 Provides the maximum entropy size. More...
 
unsigned int MinNonceLength () const
 Provides the minimum nonce size. More...
 
unsigned int MaxNonceLength () const
 Provides the maximum nonce size. More...
 
unsigned int MaxBytesPerRequest () const
 Provides the maximum size of a request to GenerateBlock. More...
 
unsigned int MaxRequestBeforeReseed () 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...
 
std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. 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 HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >

HMAC_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 HMAC 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, HMAC_DRBG limits it to INT_MAX due to the limited data range of an int.

You should reseed the generator after a fork() to avoid multiple generators with the same internal state.

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

Definition at line 291 of file drbg.h.

Constructor & Destructor Documentation

◆ HMAC_DRBG()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::HMAC_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 HMAC 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()));

  HMAC_DRBG<SHA256, 128/8, 440/8> drbg(entropy, 32, entropy+32, 16);
  drbg.GenerateBlock(result, result.size());

Definition at line 334 of file drbg.h.

Member Function Documentation

◆ SecurityStrength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::SecurityStrength ( ) 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 347 of file drbg.h.

◆ SeedLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::SeedLength ( ) 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 348 of file drbg.h.

◆ MinEntropyLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MinEntropyLength ( ) 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 349 of file drbg.h.

◆ MaxEntropyLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MaxEntropyLength ( ) 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 350 of file drbg.h.

◆ MinNonceLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MinNonceLength ( ) 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 351 of file drbg.h.

◆ MaxNonceLength()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MaxNonceLength ( ) 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 352 of file drbg.h.

◆ MaxBytesPerRequest()

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

Provides the maximum size of a request to GenerateBlock.

Returns
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 353 of file drbg.h.

◆ MaxRequestBeforeReseed()

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

Provides the maximum number of requests before a reseed.

Returns
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 354 of file drbg.h.

◆ IncorporateEntropy() [1/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void HMAC_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 356 of file drbg.h.

◆ IncorporateEntropy() [2/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void HMAC_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 359 of file drbg.h.

◆ GenerateBlock() [1/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void HMAC_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 362 of file drbg.h.

◆ GenerateBlock() [2/2]

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
void HMAC_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 365 of file drbg.h.

◆ AlgorithmProvider()

template<typename HASH = SHA256, unsigned int STRENGTH = 128/8, unsigned int SEEDLENGTH = 440/8>
std::string HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::AlgorithmProvider ( ) const
inlinevirtual

Retrieve the provider of this algorithm.

Returns
the algorithm provider

The algorithm provider can be a name like "C++", "SSE", "NEON", "AESNI", "ARMv8" and "Power8". C++ is standard C++ code. Other labels, like SSE, usually indicate a specialized implementation using instructions from a higher instruction set architecture (ISA). Future labels may include external hardware like a hardware security module (HSM).

Generally speaking Wei Dai's original IA-32 ASM code falls under "SSE2". Labels like "SSSE3" and "SSE4.1" follow after Wei's code and use intrinsics instead of ASM.

Algorithms which combine different instructions or ISAs provide the dominant one. For example on x86 AES/GCM returns "AESNI" rather than "CLMUL" or "AES+SSE4.1" or "AES+CLMUL" or "AES+SSE4.1+CLMUL".

Note
Provider is not universally implemented yet.
Since
Crypto++ 8.0

Reimplemented from Algorithm.

Definition at line 368 of file drbg.h.


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