Botan::HMAC_RNG Class Reference

#include <hmac_rng.h>

Inheritance diagram for Botan::HMAC_RNG:

Public Member Functions
void	add_entropy (const byte[], size_t)
void	add_entropy_source (EntropySource *es)
void	clear ()
	HMAC_RNG (MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
bool	is_seeded () const
std::string	name () const
byte	next_byte ()
SecureVector< byte >	random_vec (size_t bytes)
void	randomize (byte buf[], size_t len)
void	reseed (size_t poll_bits)
	~HMAC_RNG ()

Static Public Member Functions
static RandomNumberGenerator *	make_rng ()

Detailed Description

HMAC_RNG - based on the design described in "On Extract-then-Expand Key Derivation Functions and an HMAC-based KDF" by Hugo Krawczyk (henceforce, 'E-t-E')

However it actually can be parameterized with any two MAC functions, not restricted to HMAC (this variation is also described in Krawczyk's paper), for instance one could use HMAC(SHA-512) as the extractor and CMAC(AES-256) as the PRF.

Definition at line 27 of file hmac_rng.h.

Constructor & Destructor Documentation

HMAC_RNG()

Botan::HMAC_RNG::HMAC_RNG	(	MessageAuthenticationCode *	extractor,
		MessageAuthenticationCode *	prf )

Parameters

extractor	a MAC used for extracting the entropy
prf	a MAC used as a PRF using HKDF construction

Definition at line 169 of file hmac_rng.cpp.

                                                       :
   extractor(extractor_mac), prf(prf_mac)
   {
   if(!prf->valid_keylength(extractor->output_length()) ||
      !extractor->valid_keylength(prf->output_length()))
      throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
                             extractor->name() + " and " +
                             prf->name());
 
   // First PRF inputs are all zero, as specified in section 2
   K.resize(prf->output_length());
 
   counter = 0;
   output_since_reseed = 0;
   seeded = false;
 
   /*
   Normally we want to feedback PRF output into the input to the
   extractor function to ensure a single bad poll does not damage the
   RNG, but obviously that is meaningless to do on the first poll.
 
   We will want to use the PRF before we set the first key (in
   reseed), and it is a pain to keep track if it is set or
   not. Since the first time it doesn't matter anyway, just set the
   PRF key to constant zero: randomize() will not produce output
   unless is_seeded() returns true, and that will only be the case if
   the estimated entropy counter is high enough. That variable is only
   set when a reseeding is performed.
   */
   MemoryVector<byte> prf_key(extractor->output_length());
   prf->set_key(prf_key);
 
   /*
   Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
 
   This will be used during the first extraction sequence; XTS values
   after this one are generated using the PRF.
 
   If I understand the E-t-E paper correctly (specifically Section 4),
   using this fixed extractor key is safe to do.
   */
   extractor->set_key(prf->process("Botan HMAC_RNG XTS"));
   }

~HMAC_RNG()

Botan::HMAC_RNG::~HMAC_RNG

(

)

Definition at line 217 of file hmac_rng.cpp.

   {
   delete extractor;
   delete prf;
 
   std::for_each(entropy_sources.begin(), entropy_sources.end(),
                 del_fun<EntropySource>());
 
   counter = 0;
   }

Member Function Documentation

add_entropy()

void Botan::HMAC_RNG::add_entropy ( const byte in[], size_t length )

virtual

Add entropy to this RNG.

Parameters

in	a byte array containg the entropy to be added
length	the length of the byte array in

Implements Botan::RandomNumberGenerator.

Definition at line 129 of file hmac_rng.cpp.

   {
   // Add user-supplied whatever to the extractor input, and then reseed
 
   extractor->update(input, length);
   reseed(BOTAN_RNG_RESEED_POLL_BITS);
   }

References reseed().

add_entropy_source()

void Botan::HMAC_RNG::add_entropy_source ( EntropySource * source )

virtual

Add this entropy source to the RNG object

Parameters

source

the entropy source which will be retained and used by RNG

Implements Botan::RandomNumberGenerator.

Definition at line 140 of file hmac_rng.cpp.

   {
   entropy_sources.push_back(src);
   }

clear()

void Botan::HMAC_RNG::clear ( )

virtual

Clear all internally held values of this RNG.

Implements Botan::RandomNumberGenerator.

Definition at line 148 of file hmac_rng.cpp.

   {
   extractor->clear();
   prf->clear();
   zeroise(K);
   counter = 0;
   output_since_reseed = 0;
   seeded = false;
   }

References Botan::zeroise().

is_seeded()

bool Botan::HMAC_RNG::is_seeded ( ) const

inlinevirtual

Check whether this RNG is seeded.

Returns

true if this RNG was already seeded, false otherwise.

Reimplemented from Botan::RandomNumberGenerator.

Definition at line 31 of file hmac_rng.h.

{ return seeded; }

Referenced by randomize().

make_rng()

RandomNumberGenerator * Botan::RandomNumberGenerator::make_rng ( )

staticinherited

Create a seeded and active RNG object for general application use

Definition at line 29 of file rng.cpp.

   {
#if defined(BOTAN_HAS_AUTO_SEEDING_RNG)
   return new AutoSeeded_RNG;
#endif
 
   throw Algorithm_Not_Found("RandomNumberGenerator::make_rng - no RNG found");
   }

References Botan::Algorithm_Not_Found::Algorithm_Not_Found(), and RandomNumberGenerator().

name()

std::string Botan::HMAC_RNG::name ( ) const

virtual

Return the name of this object

Implements Botan::RandomNumberGenerator.

Definition at line 161 of file hmac_rng.cpp.

   {
   return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
   }

Referenced by randomize().

next_byte()

byte Botan::RandomNumberGenerator::next_byte ( )

inherited

Return a random byte

Returns

random byte

Definition at line 19 of file rng.cpp.

   {
   byte out;
   this->randomize(&out, 1);
   return out;
   }

References randomize().

Referenced by Botan::random_prime().

random_vec()

SecureVector< byte > Botan::RandomNumberGenerator::random_vec ( size_t bytes )

inlineinherited

Return a random vector

Parameters

bytes

number of bytes in the result

Returns

randomized vector of length bytes

Definition at line 40 of file rng.h.

         {
         SecureVector<byte> output(bytes);
         randomize(&output[0], output.size());
         return output;
         }

References randomize(), and Botan::MemoryRegion< T >::size().

Referenced by Botan::Client_Hello::Client_Hello(), Botan::Client_Key_Exchange::Client_Key_Exchange(), Botan::KeyPair::encryption_consistency_check(), Botan::generate_bcrypt(), Botan::generate_dsa_primes(), Botan::OctetString::OctetString(), Botan::Client_Key_Exchange::pre_master_secret(), Botan::BigInt::randomize(), Botan::Server_Hello::Server_Hello(), and Botan::KeyPair::signature_consistency_check().

randomize()

void Botan::HMAC_RNG::randomize ( byte output[], size_t length )

virtual

Randomize a byte array.

Parameters

output	the byte array to hold the random output.
length	the length of the byte array output.

Implements Botan::RandomNumberGenerator.

Definition at line 38 of file hmac_rng.cpp.

   {
   if(!is_seeded())
      throw PRNG_Unseeded(name());
 
   /*
    HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
   */
   while(length)
      {
      hmac_prf(prf, K, counter, "rng");
 
      const size_t copied = std::min<size_t>(K.size(), length);
 
      copy_mem(out, &K[0], copied);
      out += copied;
      length -= copied;
 
      output_since_reseed += copied;
 
      if(output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
         reseed(BOTAN_RNG_RESEED_POLL_BITS);
      }
   }

References Botan::copy_mem(), is_seeded(), name(), Botan::PRNG_Unseeded::PRNG_Unseeded(), and reseed().

reseed()

void Botan::HMAC_RNG::reseed ( size_t bits_to_collect )

virtual

Seed this RNG using the entropy sources it contains.

Parameters

bits_to_collect

is the number of bits of entropy to attempt to gather from the entropy sources

Implements Botan::RandomNumberGenerator.

Definition at line 66 of file hmac_rng.cpp.

   {
   /*
   Using the terminology of E-t-E, XTR is the MAC function (normally
   HMAC) seeded with XTS (below) and we form SKM, the key material, by
   fast polling each source, and then slow polling as many as we think
   we need (in the following loop), and feeding all of the poll
   results, along with any optional user input, along with, finally,
   feedback of the current PRK value, into the extractor function.
   */
 
   Entropy_Accumulator_BufferedComputation accum(*extractor, poll_bits);
 
   if(!entropy_sources.empty())
      {
      size_t poll_attempt = 0;
 
      while(!accum.polling_goal_achieved() && poll_attempt < poll_bits)
         {
         const size_t src_idx = poll_attempt % entropy_sources.size();
         entropy_sources[src_idx]->poll(accum);
         ++poll_attempt;
         }
      }
 
   /*
   * It is necessary to feed forward poll data. Otherwise, a good poll
   * (collecting a large amount of conditional entropy) followed by a
   * bad one (collecting little) would be unsafe. Do this by
   * generating new PRF outputs using the previous key and feeding
   * them into the extractor function.
   *
   * Cycle the RNG once (CTXinfo="rng"), then generate a new PRF
   * output using the CTXinfo "reseed". Provide these values as input
   * to the extractor function.
   */
   hmac_prf(prf, K, counter, "rng");
   extractor->update(K); // K is the CTXinfo=rng PRF output
 
   hmac_prf(prf, K, counter, "reseed");
   extractor->update(K); // K is the CTXinfo=reseed PRF output
 
   /* Now derive the new PRK using everything that has been fed into
      the extractor, and set the PRF key to that */
   prf->set_key(extractor->final());
 
   // Now generate a new PRF output to use as the XTS extractor salt
   hmac_prf(prf, K, counter, "xts");
   extractor->set_key(K);
 
   // Reset state
   zeroise(K);
   counter = 0;
   output_since_reseed = 0;
 
   /*
   Consider ourselves seeded once we've collected an estimated 128 bits of
   entropy in a single poll.
   */
   if(seeded == false && accum.bits_collected() >= 128)
      seeded = true;
   }

References Botan::Entropy_Accumulator::bits_collected(), Botan::Entropy_Accumulator::polling_goal_achieved(), and Botan::zeroise().

Referenced by add_entropy(), and randomize().

---

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

• src/rng/hmac_rng/hmac_rng.h
• src/rng/hmac_rng/hmac_rng.cpp