Crypto++ 8.2 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 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 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

  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

## ◆ SecurityStrength()

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

unsigned int HMAC_DRBG< HASH, STRENGTH, SEEDLENGTH >::SecurityStrength | ( |  | ) | const
| inline virtual

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
| inline virtual

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
| inline virtual

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
| inline virtual

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
| inline virtual

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
| inline virtual

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
| inline virtual

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 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
| inline virtual

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 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
| ) |  |
| inline virtual

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
| ) |  |
| inline virtual

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
| ) |  |
| inline virtual

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
| ) |  |
| inline virtual

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
| inline virtual

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:

- drbg.h