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

#include <drbg.h>

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...

virtual void	IncorporateEntropy (const byte *input, size_t length)=0
	Update RNG state with additional unpredictable values. More...

virtual void	IncorporateEntropy (const byte entropy, size_t entropyLength, const byte additional, size_t additionaLength)=0
	Update RNG state with additional unpredictable values. More...

virtual void	GenerateBlock (byte *output, size_t size)=0
	Generate random array of bytes. More...

virtual void	GenerateBlock (const byte additional, size_t additionaLength, byte output, size_t size)=0
	Generate random array of bytes. More...

virtual unsigned int	SecurityStrength () const =0
	Provides the security strength. More...

virtual unsigned int	SeedLength () const =0
	Provides the seed length. More...

virtual unsigned int	MinEntropyLength () const =0
	Provides the minimum entropy size. More...

virtual unsigned int	MaxEntropyLength () const =0
	Provides the maximum entropy size. More...

virtual unsigned int	MinNonceLength () const =0
	Provides the minimum nonce size. More...

virtual unsigned int	MaxNonceLength () const =0
	Provides the maximum nonce size. More...

virtual unsigned int	MaxBytesPerRequest () const =0
	Provides the maximum size of a request to GenerateBlock. More...

virtual unsigned int	MaxRequestBeforeReseed () const =0
	Provides the maximum number of requests before a reseed. More...

Public Member Functions inherited from RandomNumberGenerator
virtual void	IncorporateEntropy (const byte *input, size_t length)
	Update RNG state with additional unpredictable values. More...

virtual bool	CanIncorporateEntropy () const
	Determines if a generator can accept additional entropy. More...

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	GenerateBlock (byte *output, size_t size)
	Generate random array of bytes. 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...

virtual std::string	AlgorithmProvider () const
	Retrieve the provider of this algorithm. More...

Public Member Functions inherited from Clonable
virtual Clonable *	Clone () 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

HASH	NIST approved hash derived from HashTransformation
STRENGTH	security strength, in bytes
SEEDLENGTH	seed 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 2⁴⁸ 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

entropy	the entropy to instantiate the generator
entropyLength	the size of the entropy buffer
nonce	additional input to instantiate the generator
nonceLength	the size of the nonce buffer
personalization	additional input to instantiate the generator
personalizationLength	the size of the personalization buffer

Exceptions

NIST_DRBG::Err if 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

◆ StaticAlgorithmName()

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

static std::string HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::StaticAlgorithmName ( )

inlinestatic

Definition at line 307 of file drbg.h.

◆ 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 2³⁵ 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 2³⁵ 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 2⁴⁸ 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

input	the entropy to add to the generator
length	the size of the input buffer

Exceptions

NIST_DRBG::Err if 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

entropy	the entropy to add to the generator
entropyLength	the size of the input buffer
additional	additional input to add to the generator
additionaLength	the size of the additional input buffer

Exceptions

NIST_DRBG::Err if 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

output	the byte buffer
size	the length of the buffer, in bytes

Exceptions

NIST_DRBG::Err	if a reseed is required
NIST_DRBG::Err	if 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

additional	additional input to add to the generator
additionaLength	the size of the additional input buffer
output	the byte buffer
size	the length of the buffer, in bytes

Exceptions

NIST_DRBG::Err	if a reseed is required
NIST_DRBG::Err	if 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.

Member Data Documentation

◆ SECURITY_STRENGTH

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::SECURITY_STRENGTH =STRENGTH

static

Definition at line 294 of file drbg.h.

◆ SEED_LENGTH

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::SEED_LENGTH =SEEDLENGTH

static

Definition at line 295 of file drbg.h.

◆ MINIMUM_ENTROPY

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MINIMUM_ENTROPY =STRENGTH

static

Definition at line 296 of file drbg.h.

◆ MINIMUM_NONCE

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MINIMUM_NONCE =0

static

Definition at line 297 of file drbg.h.

◆ MINIMUM_ADDITIONAL

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MINIMUM_ADDITIONAL =0

static

Definition at line 298 of file drbg.h.

◆ MINIMUM_PERSONALIZATION

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MINIMUM_PERSONALIZATION =0

static

Definition at line 299 of file drbg.h.

◆ MAXIMUM_ENTROPY

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_ENTROPY =INT_MAX

static

Definition at line 300 of file drbg.h.

◆ MAXIMUM_NONCE

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_NONCE =INT_MAX

static

Definition at line 301 of file drbg.h.

◆ MAXIMUM_ADDITIONAL

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_ADDITIONAL =INT_MAX

static

Definition at line 302 of file drbg.h.

◆ MAXIMUM_PERSONALIZATION

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_PERSONALIZATION =INT_MAX

static

Definition at line 303 of file drbg.h.

◆ MAXIMUM_BYTES_PER_REQUEST

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_BYTES_PER_REQUEST =65536

static

Definition at line 304 of file drbg.h.

◆ MAXIMUM_REQUESTS_BEFORE_RESEED

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

const int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::MAXIMUM_REQUESTS_BEFORE_RESEED =INT_MAX

static

Definition at line 305 of file drbg.h.

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

drbg.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ HMAC_DRBG()

Member Function Documentation

◆ StaticAlgorithmName()

◆ SecurityStrength()

◆ SeedLength()

◆ MinEntropyLength()

◆ MaxEntropyLength()

◆ MinNonceLength()

◆ MaxNonceLength()

◆ MaxBytesPerRequest()

◆ MaxRequestBeforeReseed()

◆ IncorporateEntropy() [1/2]

◆ IncorporateEntropy() [2/2]

◆ GenerateBlock() [1/2]

◆ GenerateBlock() [2/2]

◆ AlgorithmProvider()

Member Data Documentation

◆ SECURITY_STRENGTH

◆ SEED_LENGTH

◆ MINIMUM_ENTROPY

◆ MINIMUM_NONCE

◆ MINIMUM_ADDITIONAL

◆ MINIMUM_PERSONALIZATION

◆ MAXIMUM_ENTROPY

◆ MAXIMUM_NONCE

◆ MAXIMUM_ADDITIONAL

◆ MAXIMUM_PERSONALIZATION

◆ MAXIMUM_BYTES_PER_REQUEST

◆ MAXIMUM_REQUESTS_BEFORE_RESEED