Botan: Botan::HMAC_RNG Class Reference

Botan 1.10.17

Public Member Functions | Static Public Member Functions | List of all members
Botan::HMAC_RNG Class Reference

`#include <hmac_rng.h>`

Inheritance diagram for Botan::HMAC_RNG:

## Public Member Functions
void | add_entropy (const byte[], size_t)
void | add_entropy_source (EntropySource *es)
void | clear ()
| HMAC_RNG (MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
bool | is_seeded () const
std::string | name () const
byte | next_byte ()
SecureVector< byte > | random_vec (size_t bytes)
void | randomize (byte buf[], size_t len)
void | reseed (size_t poll_bits)
| ~HMAC_RNG ()

## Static Public Member Functions
static RandomNumberGenerator * | make_rng ()

## Detailed Description

HMAC_RNG - based on the design described in "On Extract-then-Expand Key Derivation Functions and an HMAC-based KDF" by Hugo Krawczyk (henceforce, 'E-t-E')

However it actually can be parameterized with any two MAC functions, not restricted to HMAC (this variation is also described in Krawczyk's paper), for instance one could use HMAC(SHA-512) as the extractor and CMAC(AES-256) as the PRF.

Definition at line 27 of file hmac_rng.h.

## Constructor & Destructor Documentation

## ◆ HMAC_RNG()

Botan::HMAC_RNG::HMAC_RNG | ( | MessageAuthenticationCode * | extractor,
|  | MessageAuthenticationCode * | prf
| ) |  |

Parameters

  extractor | a MAC used for extracting the entropy
  prf | a MAC used as a PRF using HKDF construction

Definition at line 169 of file hmac_rng.cpp.

References Botan::MessageAuthenticationCode::name(), Botan::Buffered_Computation::output_length(), Botan::SymmetricAlgorithm::set_key(), and Botan::SymmetricAlgorithm::valid_keylength().

170 :
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 }
Botan::MemoryRegion::resize
void resize(size_t n)
Definition: secmem.h:217
Botan::Invalid_Argument
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20
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::MessageAuthenticationCode::name
virtual std::string name() const =0
Botan::Buffered_Computation::process
SecureVector< byte > process(const byte in[], size_t length)
Definition: buf_comp.h:101
Botan::Buffered_Computation::output_length
virtual size_t output_length() const =0

## ◆ ~HMAC_RNG()

Botan::HMAC_RNG::~HMAC_RNG | ( |  | ) |

Definition at line 217 of file hmac_rng.cpp.

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 }

## Member Function Documentation

## ◆ add_entropy()

void Botan::HMAC_RNG::add_entropy | ( | const byte | in[],
|  | size_t | length
| ) |  |
| virtual

Add entropy to this RNG.

Parameters

  in | a byte array containg the entropy to be added
  length | the length of the byte array in

Implements Botan::RandomNumberGenerator.

Definition at line 129 of file hmac_rng.cpp.

References reseed(), and Botan::Buffered_Computation::update().

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 }
Botan::HMAC_RNG::reseed
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
Botan::Buffered_Computation::update
void update(const byte in[], size_t length)
Definition: buf_comp.h:33

## ◆ add_entropy_source()

void Botan::HMAC_RNG::add_entropy_source | ( | EntropySource * | source | ) |
| virtual

Add this entropy source to the RNG object

Parameters

  source | the entropy source which will be retained and used by RNG

Implements Botan::RandomNumberGenerator.

Definition at line 140 of file hmac_rng.cpp.

141 {
142 entropy_sources.push_back(src);
143 }

## ◆ clear()

void Botan::HMAC_RNG::clear | ( |  | ) |
| virtual

Clear all internally held values of this RNG.

Implements Botan::RandomNumberGenerator.

Definition at line 148 of file hmac_rng.cpp.

References Botan::Algorithm::clear(), and Botan::zeroise().

149 {
150 extractor->clear();
151 prf->clear();
152 zeroise(K);
153 counter = 0;
154 output_since_reseed = 0;
155 seeded = false;
156 }
Botan::Algorithm::clear
virtual void clear()=0
Botan::zeroise
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:428

## ◆ is_seeded()

bool Botan::HMAC_RNG::is_seeded | ( |  | ) | const
| inlinevirtual

Check whether this RNG is seeded.

Returns
  true if this RNG was already seeded, false otherwise.

Reimplemented from Botan::RandomNumberGenerator.

Definition at line 31 of file hmac_rng.h.

Referenced by randomize().

31 { return seeded; }

## ◆ make_rng()

RandomNumberGenerator * Botan::RandomNumberGenerator::make_rng | ( |  | ) |
| staticinherited

Create a seeded and active RNG object for general application use

Definition at line 29 of file rng.cpp.

30 {
31 #if defined(BOTAN_HAS_AUTO_SEEDING_RNG)
32 return new AutoSeeded_RNG;
33 #endif
34
35 throw Algorithm_Not_Found("RandomNumberGenerator::make_rng - no RNG found");
36 }

## ◆ name()

std::string Botan::HMAC_RNG::name | ( |  | ) | const
| virtual

Return the name of this object

Implements Botan::RandomNumberGenerator.

Definition at line 161 of file hmac_rng.cpp.

References Botan::MessageAuthenticationCode::name().

Referenced by randomize().

162 {
163 return "HMAC_RNG(" + extractor->name() + "," + prf->name() + ")";
164 }
Botan::MessageAuthenticationCode::name
virtual std::string name() const =0

## ◆ next_byte()

byte Botan::RandomNumberGenerator::next_byte | ( |  | ) |
| inherited

Return a random byte

Returns
  random byte

Definition at line 19 of file rng.cpp.

References Botan::RandomNumberGenerator::randomize().

20 {
21 byte out;
22 this->randomize(&out, 1);
23 return out;
24 }
Botan::RandomNumberGenerator::randomize
virtual void randomize(byte output[], size_t length)=0
Botan::byte
unsigned char byte
Definition: types.h:22

## ◆ random_vec()

SecureVector<byte> Botan::RandomNumberGenerator::random_vec | ( | size_t | bytes | ) |
| inlineinherited

Return a random vector

Parameters

  bytes | number of bytes in the result

Returns
  randomized vector of length bytes

Definition at line 40 of file rng.h.

References Botan::MemoryRegion< T >::size().

41 {
42 SecureVector<byte> output(bytes);
43 randomize(&output[0], output.size());
44 return output;
45 }
Botan::RandomNumberGenerator::randomize
virtual void randomize(byte output[], size_t length)=0

## ◆ randomize()

void Botan::HMAC_RNG::randomize | ( | byte | output[],
|  | size_t | length
| ) |  |
| virtual

Randomize a byte array.

Parameters

  output | the byte array to hold the random output.
  length | the length of the byte array output.

Implements Botan::RandomNumberGenerator.

Definition at line 38 of file hmac_rng.cpp.

References Botan::copy_mem(), is_seeded(), name(), and reseed().

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 }
Botan::HMAC_RNG::is_seeded
bool is_seeded() const
Definition: hmac_rng.h:31
Botan::HMAC_RNG::reseed
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:66
Botan::copy_mem
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:22
Botan::MemoryRegion::size
size_t size() const
Definition: secmem.h:29
Botan::HMAC_RNG::name
std::string name() const
Definition: hmac_rng.cpp:161

## ◆ reseed()

void Botan::HMAC_RNG::reseed | ( | size_t | bits_to_collect | ) |
| virtual

Seed this RNG using the entropy sources it contains.

Parameters

  bits_to_collect | is the number of bits of entropy to attempt to gather from the entropy sources

Implements Botan::RandomNumberGenerator.

Definition at line 66 of file hmac_rng.cpp.

References Botan::Entropy_Accumulator::bits_collected(), Botan::Buffered_Computation::final(), Botan::Entropy_Accumulator::polling_goal_achieved(), Botan::SymmetricAlgorithm::set_key(), Botan::Buffered_Computation::update(), and Botan::zeroise().

Referenced by add_entropy(), and randomize().

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 }
Botan::SymmetricAlgorithm::set_key
void set_key(const SymmetricKey &key)
Definition: sym_algo.h:60
Botan::Buffered_Computation::update
void update(const byte in[], size_t length)
Definition: buf_comp.h:33
Botan::Buffered_Computation::final
void final(byte out[])
Definition: buf_comp.h:80
Botan::zeroise
void zeroise(MemoryRegion< T > &vec)
Definition: secmem.h:428

The documentation for this class was generated from the following files:

- src/rng/hmac_rng/hmac_rng.h
- src/rng/hmac_rng/hmac_rng.cpp