Botan  1.11.14
hmac_rng.cpp
Go to the documentation of this file.
1 /*
2 * HMAC_RNG
3 * (C) 2008-2009,2013,2015 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #include <botan/hmac_rng.h>
9 #include <botan/get_byte.h>
10 #include <botan/entropy_src.h>
11 #include <botan/internal/xor_buf.h>
12 #include <algorithm>
13 #include <chrono>
14 
15 namespace Botan {
16 
17 namespace {
18 
19 void hmac_prf(MessageAuthenticationCode& prf,
20  secure_vector<byte>& K,
21  u32bit& counter,
22  const std::string& label)
23  {
24  typedef std::chrono::high_resolution_clock clock;
25 
26  auto timestamp = clock::now().time_since_epoch().count();
27 
28  prf.update(K);
29  prf.update(label);
30  prf.update_be(timestamp);
31  prf.update_be(counter);
32  prf.final(&K[0]);
33 
34  ++counter;
35  }
36 
37 }
38 
39 /*
40 * HMAC_RNG Constructor
41 */
44  m_extractor(extractor), m_prf(prf)
45  {
46  if(!m_prf->valid_keylength(m_extractor->output_length()) ||
47  !m_extractor->valid_keylength(m_prf->output_length()))
48  throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
49  m_extractor->name() + " and " +
50  m_prf->name());
51 
52  // First PRF inputs are all zero, as specified in section 2
53  m_K.resize(m_prf->output_length());
54 
55  /*
56  Normally we want to feedback PRF outputs to the extractor function
57  to ensure a single bad poll does not reduce entropy. Thus in reseed
58  we'll want to invoke the PRF before we reset the PRF key, but until
59  the first reseed the PRF is unkeyed. Rather than trying to keep
60  track of this, just set the initial PRF key to constant zero.
61  Since all PRF inputs in the first reseed are constants, this
62  amounts to suffixing the seed in the first poll with a fixed
63  constant string.
64 
65  The PRF key will not be used to generate outputs until after reseed
66  sets m_seeded to true.
67  */
68  secure_vector<byte> prf_key(m_extractor->output_length());
69  m_prf->set_key(prf_key);
70 
71  /*
72  Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
73 
74  This will be used during the first extraction sequence; XTS values
75  after this one are generated using the PRF.
76 
77  If I understand the E-t-E paper correctly (specifically Section 4),
78  using this fixed extractor key is safe to do.
79  */
80  m_extractor->set_key(prf->process("Botan HMAC_RNG XTS"));
81  }
82 
83 /*
84 * Generate a buffer of random bytes
85 */
86 void HMAC_RNG::randomize(byte out[], size_t length)
87  {
88  if(!is_seeded())
89  {
90  reseed(256);
91  if(!is_seeded())
92  throw PRNG_Unseeded(name());
93  }
94 
95  const size_t max_per_prf_iter = m_prf->output_length() / 2;
96 
97  m_output_since_reseed += length;
98 
99  if(m_output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
100  reseed(BOTAN_RNG_RESEED_POLL_BITS);
101 
102  /*
103  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
104  */
105  while(length)
106  {
107  hmac_prf(*m_prf, m_K, m_counter, "rng");
108 
109  const size_t copied = std::min<size_t>(length, max_per_prf_iter);
110 
111  copy_mem(out, &m_K[0], copied);
112  out += copied;
113  length -= copied;
114  }
115  }
116 
117 /*
118 * Poll for entropy and reset the internal keys
119 */
120 void HMAC_RNG::reseed(size_t poll_bits)
121  {
122  /*
123  Using the terminology of E-t-E, XTR is the MAC function (normally
124  HMAC) seeded with XTS (below) and we form SKM, the key material, by
125  polling as many sources as we think needed to reach our polling
126  goal. We then also include feedback of the current PRK so that
127  a bad poll doesn't wipe us out.
128  */
129 
130  double bits_collected = 0;
131 
132  Entropy_Accumulator accum(
133  [&](const byte in[], size_t in_len, double entropy_estimate)
134  {
135  m_extractor->update(in, in_len);
136  bits_collected += entropy_estimate;
137  return (bits_collected >= poll_bits);
138  });
139 
141 
142  /*
143  * It is necessary to feed forward poll data. Otherwise, a good poll
144  * (collecting a large amount of conditional entropy) followed by a
145  * bad one (collecting little) would be unsafe. Do this by
146  * generating new PRF outputs using the previous key and feeding
147  * them into the extractor function.
148  *
149  * Cycle the RNG once (CTXinfo="rng"), then generate a new PRF
150  * output using the CTXinfo "reseed". Provide these values as input
151  * to the extractor function.
152  */
153  hmac_prf(*m_prf, m_K, m_counter, "rng");
154  m_extractor->update(m_K); // K is the CTXinfo=rng PRF output
155 
156  hmac_prf(*m_prf, m_K, m_counter, "reseed");
157  m_extractor->update(m_K); // K is the CTXinfo=reseed PRF output
158 
159  /* Now derive the new PRK using everything that has been fed into
160  the extractor, and set the PRF key to that */
161  m_prf->set_key(m_extractor->final());
162 
163  // Now generate a new PRF output to use as the XTS extractor salt
164  hmac_prf(*m_prf, m_K, m_counter, "xts");
165  m_extractor->set_key(m_K);
166 
167  // Reset state
168  zeroise(m_K);
169  m_counter = 0;
170 
171  m_collected_entropy_estimate =
172  std::min<size_t>(m_collected_entropy_estimate + bits_collected,
173  m_extractor->output_length() * 8);
174 
175  m_output_since_reseed = 0;
176  }
177 
179  {
180  return (m_collected_entropy_estimate >= 256);
181  }
182 
183 /*
184 * Add user-supplied entropy to the extractor input
185 */
186 void HMAC_RNG::add_entropy(const byte input[], size_t length)
187  {
188  m_extractor->update(input, length);
189  reseed(BOTAN_RNG_RESEED_POLL_BITS);
190  }
191 
192 /*
193 * Clear memory of sensitive data
194 */
196  {
197  m_collected_entropy_estimate = 0;
198  m_extractor->clear();
199  m_prf->clear();
200  zeroise(m_K);
201  m_counter = 0;
202  }
203 
204 /*
205 * Return the name of this type
206 */
207 std::string HMAC_RNG::name() const
208  {
209  return "HMAC_RNG(" + m_extractor->name() + "," + m_prf->name() + ")";
210  }
211 
212 }
std::string name() const
Definition: hmac_rng.cpp:207
void add_entropy(const byte[], size_t)
Definition: hmac_rng.cpp:186
static void poll_available_sources(class Entropy_Accumulator &accum)
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:120
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
secure_vector< byte > process(const byte in[], size_t length)
Definition: buf_comp.h:118
bool is_seeded() const
Definition: hmac_rng.cpp:178
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:93
HMAC_RNG(MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
Definition: hmac_rng.cpp:42
uint32_t u32bit
Definition: types.h:33
uint8_t byte
Definition: types.h:31
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:39
void randomize(byte buf[], size_t len)
Definition: hmac_rng.cpp:86
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:168