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