Botan  1.10.9
hmac_rng.cpp
Go to the documentation of this file.
1 /*
2 * HMAC_RNG
3 * (C) 2008-2009 Jack Lloyd
4 *
5 * Distributed under the terms of the Botan license
6 */
7 
8 #include <botan/hmac_rng.h>
9 #include <botan/get_byte.h>
10 #include <botan/time.h>
11 #include <botan/internal/xor_buf.h>
12 #include <botan/internal/stl_util.h>
13 #include <algorithm>
14 
15 namespace Botan {
16 
17 namespace {
18 
19 void hmac_prf(MessageAuthenticationCode* prf,
20  MemoryRegion<byte>& K,
21  u32bit& counter,
22  const std::string& label)
23  {
24  prf->update(K);
25  prf->update(label);
26  prf->update_be(counter);
27  prf->update_be(get_nanoseconds_clock());
28  prf->final(&K[0]);
29 
30  ++counter;
31  }
32 
33 }
34 
35 /*
36 * Generate a buffer of random bytes
37 */
38 void HMAC_RNG::randomize(byte out[], size_t length)
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  }
62 
63 /*
64 * Poll for entropy and reset the internal keys
65 */
66 void HMAC_RNG::reseed(size_t poll_bits)
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  }
128 
129 void HMAC_RNG::add_entropy(const byte input[], size_t length)
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  }
136 
137 /*
138 * Add another entropy source to the list
139 */
141  {
142  entropy_sources.push_back(src);
143  }
144 
145 /*
146 * Clear memory of sensitive data
147 */
149  {
150  extractor->clear();
151  prf->clear();
152  zeroise(K);
153  counter = 0;
154  output_since_reseed = 0;
155  seeded = false;
156  }
157 
158 /*
159 * Return the name of this type
160 */
161 std::string HMAC_RNG::name() const
162  {
163  return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
164  }
165 
166 /*
167 * HMAC_RNG Constructor
168 */
170  MessageAuthenticationCode* prf_mac) :
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  }
213 
214 /*
215 * HMAC_RNG Destructor
216 */
218  {
219  delete extractor;
220  delete prf;
221 
222  std::for_each(entropy_sources.begin(), entropy_sources.end(),
224 
225  counter = 0;
226  }
227 
228 }
std::string name() const
Definition: hmac_rng.cpp:161
void add_entropy(const byte[], size_t)
Definition: hmac_rng.cpp:129
u64bit get_nanoseconds_clock()
Definition: time.cpp:93
virtual void clear()=0
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
unsigned char byte
Definition: types.h:22
bool valid_keylength(size_t length) const
Definition: sym_algo.h:51
bool is_seeded() const
Definition: hmac_rng.h:31
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:60
HMAC_RNG(MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
Definition: hmac_rng.cpp:169
virtual std::string name() const =0
void update(const byte in[], size_t length)
Definition: buf_comp.h:33
bool polling_goal_achieved() const
Definition: entropy_src.h:50
size_t bits_collected() const
Definition: entropy_src.h:44
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:22
void final(byte out[])
Definition: buf_comp.h:80
void randomize(byte buf[], size_t len)
Definition: hmac_rng.cpp:38
void add_entropy_source(EntropySource *es)
Definition: hmac_rng.cpp:140
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:415
virtual size_t output_length() const =0
unsigned int u32bit
Definition: types.h:32