Botan  1.11.26
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/entropy_src.h>
10 #include <algorithm>
11 #include <chrono>
12 
13 namespace Botan {
14 
15 /*
16 * HMAC_RNG Constructor
17 */
20  m_extractor(extractor), m_prf(prf)
21  {
22  if(!m_prf->valid_keylength(m_extractor->output_length()) ||
23  !m_extractor->valid_keylength(m_prf->output_length()))
24  {
25  throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
26  m_extractor->name() + " and " +
27  m_prf->name());
28  }
29 
30  this->clear();
31  }
32 
34  {
35  m_collected_entropy_estimate = 0;
36  m_counter = 0;
37 
38  // First PRF inputs are all zero, as specified in section 2
39  m_K.resize(m_prf->output_length());
40  zeroise(m_K);
41 
42  /*
43  Normally we want to feedback PRF outputs to the extractor function
44  to ensure a single bad poll does not reduce entropy. Thus in reseed
45  we'll want to invoke the PRF before we reset the PRF key, but until
46  the first reseed the PRF is unkeyed. Rather than trying to keep
47  track of this, just set the initial PRF key to constant zero.
48  Since all PRF inputs in the first reseed are constants, this
49  amounts to suffixing the seed in the first poll with a fixed
50  constant string.
51 
52  The PRF key will not be used to generate outputs until after reseed
53  sets m_seeded to true.
54  */
55  std::vector<byte> prf_zero_key(m_extractor->output_length());
56  m_prf->set_key(prf_zero_key.data(), prf_zero_key.size());
57 
58  /*
59  Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
60 
61  This will be used during the first extraction sequence; XTS values
62  after this one are generated using the PRF.
63 
64  If I understand the E-t-E paper correctly (specifically Section 4),
65  using this fixed initial extractor key is safe to do.
66  */
67  m_extractor->set_key(m_prf->process("Botan HMAC_RNG XTS"));
68  }
69 
70 void HMAC_RNG::new_K_value(byte label)
71  {
72  typedef std::chrono::high_resolution_clock clock;
73 
74  m_prf->update(m_K);
75  m_prf->update_be(clock::now().time_since_epoch().count());
76  m_prf->update_be(m_counter++);
77  m_prf->update(label);
78  m_prf->final(m_K.data());
79  }
80 
81 /*
82 * Generate a buffer of random bytes
83 */
84 void HMAC_RNG::randomize(byte out[], size_t length)
85  {
86  if(!is_seeded())
87  {
88  reseed(256);
89  if(!is_seeded())
90  throw PRNG_Unseeded(name());
91  }
92 
93  const size_t max_per_prf_iter = m_prf->output_length() / 2;
94 
95  m_output_since_reseed += length;
96 
97  if(m_output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
98  {
100  BOTAN_RNG_RESEED_POLL_BITS,
101  BOTAN_RNG_AUTO_RESEED_TIMEOUT);
102  }
103 
104  /*
105  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
106  */
107  while(length)
108  {
109  new_K_value(Running);
110 
111  const size_t copied = std::min<size_t>(length, max_per_prf_iter);
112 
113  copy_mem(out, m_K.data(), copied);
114  out += copied;
115  length -= copied;
116  }
117  }
118 
120  size_t poll_bits,
121  std::chrono::milliseconds timeout)
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  typedef std::chrono::system_clock clock;
132  auto deadline = clock::now() + timeout;
133 
134  double bits_collected = 0;
135 
136  Entropy_Accumulator accum([&](const byte in[], size_t in_len, double entropy_estimate) {
137  m_extractor->update(in, in_len);
138  bits_collected += entropy_estimate;
139  return (bits_collected >= poll_bits || clock::now() > deadline);
140  });
141 
142  srcs.poll(accum);
143 
144  /*
145  * It is necessary to feed forward poll data. Otherwise, a good poll
146  * (collecting a large amount of conditional entropy) followed by a
147  * bad one (collecting little) would be unsafe. Do this by
148  * generating new PRF outputs using the previous key and feeding
149  * them into the extractor function.
150  */
151  new_K_value(Reseed);
152  m_extractor->update(m_K); // K is the CTXinfo=reseed PRF output
153 
154  /* Now derive the new PRK using everything that has been fed into
155  the extractor, and set the PRF key to that */
156  m_prf->set_key(m_extractor->final());
157 
158  // Now generate a new PRF output to use as the XTS extractor salt
159  new_K_value(ExtractorSeed);
160  m_extractor->set_key(m_K);
161 
162  // Reset state
163  zeroise(m_K);
164  m_counter = 0;
165 
166  m_collected_entropy_estimate =
167  std::min<size_t>(m_collected_entropy_estimate + bits_collected,
168  m_extractor->output_length() * 8);
169 
170  m_output_since_reseed = 0;
171 
172  return static_cast<size_t>(bits_collected);
173  }
174 
176  {
177  return (m_collected_entropy_estimate >= 256);
178  }
179 
180 /*
181 * Add user-supplied entropy to the extractor input then reseed
182 * to incorporate it into the state
183 */
184 void HMAC_RNG::add_entropy(const byte input[], size_t length)
185  {
186  m_extractor->update(input, length);
187 
189  BOTAN_RNG_RESEED_POLL_BITS,
190  BOTAN_RNG_RESEED_DEFAULT_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 }
void add_entropy(const byte[], size_t) override
Definition: hmac_rng.cpp:184
size_t reseed(size_t bits_to_collect)
Definition: rng.cpp:14
std::string name() const override
Definition: hmac_rng.cpp:196
HMAC_RNG(MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
Definition: hmac_rng.cpp:18
void clear() override
Definition: hmac_rng.cpp:33
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:43
Definition: alg_id.cpp:13
bool is_seeded() const override
Definition: hmac_rng.cpp:175
static Entropy_Sources & global_sources()
void poll(Entropy_Accumulator &accum)
void randomize(byte buf[], size_t len) override
Definition: hmac_rng.cpp:84
size_t reseed_with_sources(Entropy_Sources &srcs, size_t poll_bits, std::chrono::milliseconds poll_timeout) override
Definition: hmac_rng.cpp:119
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:186
std::uint8_t byte
Definition: types.h:31