Botan  1.11.16
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 /*
18 * HMAC_RNG Constructor
19 */
22  m_extractor(extractor), m_prf(prf)
23  {
24  if(!m_prf->valid_keylength(m_extractor->output_length()) ||
25  !m_extractor->valid_keylength(m_prf->output_length()))
26  {
27  throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
28  m_extractor->name() + " and " +
29  m_prf->name());
30  }
31 
32  this->clear();
33  }
34 
36  {
37  m_collected_entropy_estimate = 0;
38  m_counter = 0;
39 
40  // First PRF inputs are all zero, as specified in section 2
41  m_K.resize(m_prf->output_length());
42  zeroise(m_K);
43 
44  /*
45  Normally we want to feedback PRF outputs to the extractor function
46  to ensure a single bad poll does not reduce entropy. Thus in reseed
47  we'll want to invoke the PRF before we reset the PRF key, but until
48  the first reseed the PRF is unkeyed. Rather than trying to keep
49  track of this, just set the initial PRF key to constant zero.
50  Since all PRF inputs in the first reseed are constants, this
51  amounts to suffixing the seed in the first poll with a fixed
52  constant string.
53 
54  The PRF key will not be used to generate outputs until after reseed
55  sets m_seeded to true.
56  */
57  std::vector<byte> prf_zero_key(m_extractor->output_length());
58  m_prf->set_key(&prf_zero_key[0], prf_zero_key.size());
59 
60  /*
61  Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
62 
63  This will be used during the first extraction sequence; XTS values
64  after this one are generated using the PRF.
65 
66  If I understand the E-t-E paper correctly (specifically Section 4),
67  using this fixed initial extractor key is safe to do.
68  */
69  m_extractor->set_key(m_prf->process("Botan HMAC_RNG XTS"));
70  }
71 
72 void HMAC_RNG::new_K_value(byte label)
73  {
74  typedef std::chrono::high_resolution_clock clock;
75 
76  m_prf->update(m_K);
77  m_prf->update_be(clock::now().time_since_epoch().count());
78  m_prf->update_be(m_counter++);
79  m_prf->update(label);
80  m_prf->final(&m_K[0]);
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_with_timeout(BOTAN_RNG_RESEED_POLL_BITS, BOTAN_RNG_AUTO_RESEED_TIMEOUT);
101 
102  /*
103  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
104  */
105  while(length)
106  {
107  new_K_value(Running);
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  reseed_with_timeout(poll_bits, BOTAN_RNG_RESEED_DEFAULT_TIMEOUT);
123  }
124 
125 void HMAC_RNG::reseed_with_timeout(size_t poll_bits, std::chrono::milliseconds timeout)
126  {
127  /*
128  Using the terminology of E-t-E, XTR is the MAC function (normally
129  HMAC) seeded with XTS (below) and we form SKM, the key material, by
130  polling as many sources as we think needed to reach our polling
131  goal. We then also include feedback of the current PRK so that
132  a bad poll doesn't wipe us out.
133  */
134 
135  double bits_collected = 0;
136 
137  typedef std::chrono::high_resolution_clock clock;
138  auto deadline = clock::now() + timeout;
139 
140  Entropy_Accumulator accum(
141  [&](const byte in[], size_t in_len, double entropy_estimate)
142  {
143  m_extractor->update(in, in_len);
144  bits_collected += entropy_estimate;
145  return (bits_collected >= poll_bits || clock::now() > deadline);
146  });
147 
149 
150  /*
151  * It is necessary to feed forward poll data. Otherwise, a good poll
152  * (collecting a large amount of conditional entropy) followed by a
153  * bad one (collecting little) would be unsafe. Do this by
154  * generating new PRF outputs using the previous key and feeding
155  * them into the extractor function.
156  */
157  new_K_value(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  new_K_value(ExtractorSeed);
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_with_timeout(BOTAN_RNG_RESEED_POLL_BITS, BOTAN_RNG_AUTO_RESEED_TIMEOUT);
191  }
192 
193 /*
194 * Return the name of this type
195 */
196 std::string HMAC_RNG::name() const
197  {
198  return "HMAC_RNG(" + m_extractor->name() + "," + m_prf->name() + ")";
199  }
200 
201 }
static void poll_available_sources(class Entropy_Accumulator &accum)
void add_entropy(const byte[], size_t) override
Definition: hmac_rng.cpp:187
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
std::string name() const override
Definition: hmac_rng.cpp:196
void reseed_with_timeout(size_t poll_bits, std::chrono::milliseconds ms)
Definition: hmac_rng.cpp:125
HMAC_RNG(MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
Definition: hmac_rng.cpp:20
void clear() override
Definition: hmac_rng.cpp:35
uint8_t byte
Definition: types.h:31
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:39
void reseed(size_t poll_bits) override
Definition: hmac_rng.cpp:120
bool is_seeded() const override
Definition: hmac_rng.cpp:179
void randomize(byte buf[], size_t len) override
Definition: hmac_rng.cpp:86
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:168