Botan 1.10.17

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 */
140 void HMAC_RNG::add_entropy_source(EntropySource* src)
141 {
142 entropy_sources.push_back(src);
143 }
144
145 /*
146 * Clear memory of sensitive data
147 */
148 void HMAC_RNG::clear()
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 */
169 HMAC_RNG::HMAC_RNG(MessageAuthenticationCode* extractor_mac,
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 */
217 HMAC_RNG::~HMAC_RNG()
218 {
219 delete extractor;
220 delete prf;
221
222 std::for_each(entropy_sources.begin(), entropy_sources.end(),
223 del_fun<EntropySource>());
224
225 counter = 0;
226 }
227
228 }
Botan::HMAC_RNG::add_entropy
void add_entropy(const byte[], size_t)
Definition: hmac_rng.cpp:129
Botan::get_nanoseconds_clock
u64bit get_nanoseconds_clock()
Definition: time.cpp:93
Botan::Algorithm::clear
virtual void clear()=0
Botan::HMAC_RNG::is_seeded
bool is_seeded() const
Definition: hmac_rng.h:31
Botan::Entropy_Accumulator_BufferedComputation
Definition: entropy_src.h:98
Botan::HMAC_RNG::reseed
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
Botan::EntropySource
Definition: entropy_src.h:122
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
Botan::MessageAuthenticationCode
Definition: mac.h:20
Botan::HMAC_RNG::clear
void clear()
Definition: hmac_rng.cpp:148
Botan::byte
unsigned char byte
Definition: types.h:22
Botan::SymmetricAlgorithm::valid_keylength
bool valid_keylength(size_t length) const
Definition: sym_algo.h:51
Botan::SymmetricAlgorithm::set_key
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:60
Botan::HMAC_RNG::HMAC_RNG
HMAC_RNG(MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
Definition: hmac_rng.cpp:169
Botan::MessageAuthenticationCode::name
virtual std::string name() const =0
Botan::Buffered_Computation::update
void update(const byte in[], size_t length)
Definition: buf_comp.h:33
Botan::copy_mem
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:22
Botan
Definition: algo_base.h:14
Botan::MemoryVector< byte >
Botan::Buffered_Computation::final
void final(byte out[])
Definition: buf_comp.h:80
Botan::Entropy_Accumulator::polling_goal_achieved
bool polling_goal_achieved() const
Definition: entropy_src.h:50
Botan::del_fun
Definition: stl_util.h:57
Botan::HMAC_RNG::name
std::string name() const
Definition: hmac_rng.cpp:161
Botan::HMAC_RNG::randomize
void randomize(byte buf[], size_t len)
Definition: hmac_rng.cpp:38
Botan::Entropy_Accumulator::bits_collected
size_t bits_collected() const
Definition: entropy_src.h:44
Botan::HMAC_RNG::add_entropy_source
void add_entropy_source(EntropySource *es)
Definition: hmac_rng.cpp:140
Botan::zeroise
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:428
Botan::Buffered_Computation::output_length
virtual size_t output_length() const =0
Botan::PRNG_Unseeded
Definition: exceptn.h:89
Botan::HMAC_RNG::~HMAC_RNG
~HMAC_RNG()
Definition: hmac_rng.cpp:217
Botan::u32bit
unsigned int u32bit
Definition: types.h:32