Botan  1.10.9
Public Member Functions | Static Public Member Functions | List of all members
Botan::HMAC_RNG Class Reference

#include <hmac_rng.h>

Inheritance diagram for Botan::HMAC_RNG:
Botan::RandomNumberGenerator

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< byterandom_vec (size_t bytes)
 
void randomize (byte buf[], size_t len)
 
void reseed (size_t poll_bits)
 
 ~HMAC_RNG ()
 

Static Public Member Functions

static RandomNumberGeneratormake_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

Botan::HMAC_RNG::HMAC_RNG ( MessageAuthenticationCode extractor,
MessageAuthenticationCode prf 
)
Parameters
extractora MAC used for extracting the entropy
prfa MAC used as a PRF using HKDF construction

Definition at line 169 of file hmac_rng.cpp.

References Botan::MessageAuthenticationCode::name(), Botan::Buffered_Computation::output_length(), Botan::SymmetricAlgorithm::set_key(), and Botan::SymmetricAlgorithm::valid_keylength().

170  :
171  extractor(extractor_mac), prf(prf_mac)
172  {
173  if(!prf->valid_keylength(extractor->output_length()) ||
174  !extractor->valid_keylength(prf->output_length()))
175  throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
176  extractor->name() + " and " +
177  prf->name());
178 
179  // First PRF inputs are all zero, as specified in section 2
180  K.resize(prf->output_length());
181 
182  counter = 0;
183  output_since_reseed = 0;
184  seeded = false;
185 
186  /*
187  Normally we want to feedback PRF output into the input to the
188  extractor function to ensure a single bad poll does not damage the
189  RNG, but obviously that is meaningless to do on the first poll.
190 
191  We will want to use the PRF before we set the first key (in
192  reseed), and it is a pain to keep track if it is set or
193  not. Since the first time it doesn't matter anyway, just set the
194  PRF key to constant zero: randomize() will not produce output
195  unless is_seeded() returns true, and that will only be the case if
196  the estimated entropy counter is high enough. That variable is only
197  set when a reseeding is performed.
198  */
199  MemoryVector<byte> prf_key(extractor->output_length());
200  prf->set_key(prf_key);
201 
202  /*
203  Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
204 
205  This will be used during the first extraction sequence; XTS values
206  after this one are generated using the PRF.
207 
208  If I understand the E-t-E paper correctly (specifically Section 4),
209  using this fixed extractor key is safe to do.
210  */
211  extractor->set_key(prf->process("Botan HMAC_RNG XTS"));
212  }
void resize(size_t n)
Definition: secmem.h:211
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
bool valid_keylength(size_t length) const
Definition: sym_algo.h:51
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:60
virtual std::string name() const =0
SecureVector< byte > process(const byte in[], size_t length)
Definition: buf_comp.h:101
virtual size_t output_length() const =0
Botan::HMAC_RNG::~HMAC_RNG ( )

Definition at line 217 of file hmac_rng.cpp.

218  {
219  delete extractor;
220  delete prf;
221 
222  std::for_each(entropy_sources.begin(), entropy_sources.end(),
223  del_fun<EntropySource>());
224 
225  counter = 0;
226  }

Member Function Documentation

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

Add entropy to this RNG.

Parameters
ina byte array containg the entropy to be added
lengththe length of the byte array in

Implements Botan::RandomNumberGenerator.

Definition at line 129 of file hmac_rng.cpp.

References reseed(), and Botan::Buffered_Computation::update().

130  {
131  // Add user-supplied whatever to the extractor input, and then reseed
132 
133  extractor->update(input, length);
134  reseed(BOTAN_RNG_RESEED_POLL_BITS);
135  }
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
void update(const byte in[], size_t length)
Definition: buf_comp.h:33
void Botan::HMAC_RNG::add_entropy_source ( EntropySource source)
virtual

Add this entropy source to the RNG object

Parameters
sourcethe entropy source which will be retained and used by RNG

Implements Botan::RandomNumberGenerator.

Definition at line 140 of file hmac_rng.cpp.

141  {
142  entropy_sources.push_back(src);
143  }
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.

References Botan::Algorithm::clear(), and Botan::zeroise().

149  {
150  extractor->clear();
151  prf->clear();
152  zeroise(K);
153  counter = 0;
154  output_since_reseed = 0;
155  seeded = false;
156  }
virtual void clear()=0
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:415
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.

Referenced by randomize().

31 { return seeded; }
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.

30  {
31 #if defined(BOTAN_HAS_AUTO_SEEDING_RNG)
32  return new AutoSeeded_RNG;
33 #endif
34 
35  throw Algorithm_Not_Found("RandomNumberGenerator::make_rng - no RNG found");
36  }
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.

References Botan::MessageAuthenticationCode::name().

Referenced by randomize().

162  {
163  return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
164  }
virtual std::string name() const =0
byte Botan::RandomNumberGenerator::next_byte ( )
inherited

Return a random byte

Returns
random byte

Definition at line 19 of file rng.cpp.

References Botan::RandomNumberGenerator::randomize().

Referenced by Botan::random_prime().

20  {
21  byte out;
22  this->randomize(&out, 1);
23  return out;
24  }
virtual void randomize(byte output[], size_t length)=0
unsigned char byte
Definition: types.h:22
SecureVector<byte> Botan::RandomNumberGenerator::random_vec ( size_t  bytes)
inlineinherited

Return a random vector

Parameters
bytesnumber of bytes in the result
Returns
randomized vector of length bytes

Definition at line 40 of file rng.h.

References 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().

41  {
42  SecureVector<byte> output(bytes);
43  randomize(&output[0], output.size());
44  return output;
45  }
virtual void randomize(byte output[], size_t length)=0
void Botan::HMAC_RNG::randomize ( byte  output[],
size_t  length 
)
virtual

Randomize a byte array.

Parameters
outputthe byte array to hold the random output.
lengththe length of the byte array output.

Implements Botan::RandomNumberGenerator.

Definition at line 38 of file hmac_rng.cpp.

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

39  {
40  if(!is_seeded())
41  throw PRNG_Unseeded(name());
42 
43  /*
44  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
45  */
46  while(length)
47  {
48  hmac_prf(prf, K, counter, "rng");
49 
50  const size_t copied = std::min<size_t>(K.size(), length);
51 
52  copy_mem(out, &K[0], copied);
53  out += copied;
54  length -= copied;
55 
56  output_since_reseed += copied;
57 
58  if(output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
59  reseed(BOTAN_RNG_RESEED_POLL_BITS);
60  }
61  }
std::string name() const
Definition: hmac_rng.cpp:161
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
bool is_seeded() const
Definition: hmac_rng.h:31
size_t size() const
Definition: secmem.h:29
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:22
void Botan::HMAC_RNG::reseed ( size_t  bits_to_collect)
virtual

Seed this RNG using the entropy sources it contains.

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

References Botan::Entropy_Accumulator::bits_collected(), Botan::Buffered_Computation::final(), Botan::Entropy_Accumulator::polling_goal_achieved(), Botan::SymmetricAlgorithm::set_key(), Botan::Buffered_Computation::update(), and Botan::zeroise().

Referenced by add_entropy(), and randomize().

67  {
68  /*
69  Using the terminology of E-t-E, XTR is the MAC function (normally
70  HMAC) seeded with XTS (below) and we form SKM, the key material, by
71  fast polling each source, and then slow polling as many as we think
72  we need (in the following loop), and feeding all of the poll
73  results, along with any optional user input, along with, finally,
74  feedback of the current PRK value, into the extractor function.
75  */
76 
77  Entropy_Accumulator_BufferedComputation accum(*extractor, poll_bits);
78 
79  if(!entropy_sources.empty())
80  {
81  size_t poll_attempt = 0;
82 
83  while(!accum.polling_goal_achieved() && poll_attempt < poll_bits)
84  {
85  const size_t src_idx = poll_attempt % entropy_sources.size();
86  entropy_sources[src_idx]->poll(accum);
87  ++poll_attempt;
88  }
89  }
90 
91  /*
92  * It is necessary to feed forward poll data. Otherwise, a good poll
93  * (collecting a large amount of conditional entropy) followed by a
94  * bad one (collecting little) would be unsafe. Do this by
95  * generating new PRF outputs using the previous key and feeding
96  * them into the extractor function.
97  *
98  * Cycle the RNG once (CTXinfo="rng"), then generate a new PRF
99  * output using the CTXinfo "reseed". Provide these values as input
100  * to the extractor function.
101  */
102  hmac_prf(prf, K, counter, "rng");
103  extractor->update(K); // K is the CTXinfo=rng PRF output
104 
105  hmac_prf(prf, K, counter, "reseed");
106  extractor->update(K); // K is the CTXinfo=reseed PRF output
107 
108  /* Now derive the new PRK using everything that has been fed into
109  the extractor, and set the PRF key to that */
110  prf->set_key(extractor->final());
111 
112  // Now generate a new PRF output to use as the XTS extractor salt
113  hmac_prf(prf, K, counter, "xts");
114  extractor->set_key(K);
115 
116  // Reset state
117  zeroise(K);
118  counter = 0;
119  output_since_reseed = 0;
120 
121  /*
122  Consider ourselves seeded once we've collected an estimated 128 bits of
123  entropy in a single poll.
124  */
125  if(seeded == false && accum.bits_collected() >= 128)
126  seeded = true;
127  }
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:60
void update(const byte in[], size_t length)
Definition: buf_comp.h:33
void final(byte out[])
Definition: buf_comp.h:80
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:415

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