Botan  1.11.10
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:
Botan::RandomNumberGenerator

Public Member Functions

void add_entropy (const byte[], size_t)
 
void clear ()
 
 HMAC_RNG (MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
 
bool is_seeded () const
 
std::string name () const
 
byte next_byte ()
 
virtual secure_vector< byterandom_vec (size_t bytes)
 
void randomize (byte buf[], size_t len)
 
void reseed (size_t poll_bits)
 

Static Public Member Functions

static RandomNumberGeneratormake_rng ()
 
static std::unique_ptr
< RandomNumberGenerator
make_rng (class Algorithm_Factory &af)
 

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

Botan::HMAC_RNG::HMAC_RNG ( MessageAuthenticationCode extractor,
MessageAuthenticationCode prf 
)
Parameters
extractora MAC used for extracting the entropy
prfa MAC used as a PRF using HKDF construction

Definition at line 43 of file hmac_rng.cpp.

References Botan::Buffered_Computation::process().

44  :
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  }
std::invalid_argument Invalid_Argument
Definition: exceptn.h:20

Member Function Documentation

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

Add entropy to this RNG.

Parameters
ina byte array containg the entropy to be added
lengththe length of the byte array in

Implements Botan::RandomNumberGenerator.

Definition at line 187 of file hmac_rng.cpp.

References reseed().

188  {
189  m_extractor->update(input, length);
190  reseed(BOTAN_RNG_RESEED_POLL_BITS);
191  }
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:121
void Botan::HMAC_RNG::clear ( )
virtual

Clear all internally held values of this RNG.

Implements Botan::RandomNumberGenerator.

Definition at line 196 of file hmac_rng.cpp.

References Botan::zeroise().

197  {
198  m_collected_entropy_estimate = 0;
199  m_extractor->clear();
200  m_prf->clear();
201  zeroise(m_K);
202  m_counter = 0;
203  }
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:166
bool Botan::HMAC_RNG::is_seeded ( ) const
virtual

Check whether this RNG is seeded.

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

Implements Botan::RandomNumberGenerator.

Definition at line 179 of file hmac_rng.cpp.

Referenced by randomize().

180  {
181  return (m_collected_entropy_estimate >= 256);
182  }
RandomNumberGenerator * Botan::RandomNumberGenerator::make_rng ( )
staticinherited

Create a seeded and active RNG object for general application use Added in 1.8.0

Definition at line 14 of file rng.cpp.

References Botan::Global_State_Management::global_state().

15  {
16  return make_rng(global_state().algorithm_factory()).release();
17  }
static RandomNumberGenerator * make_rng()
Definition: rng.cpp:14
Library_State & global_state()
std::unique_ptr< RandomNumberGenerator > Botan::RandomNumberGenerator::make_rng ( class Algorithm_Factory af)
staticinherited

Create a seeded and active RNG object for general application use Added in 1.11.5

Definition at line 22 of file rng.cpp.

References Botan::Algorithm_Factory::make_mac().

23  {
24  std::unique_ptr<RandomNumberGenerator> rng(
25  new HMAC_RNG(af.make_mac("HMAC(SHA-512)"),
26  af.make_mac("HMAC(SHA-256)"))
27  );
28 
29  rng->reseed(256);
30 
31  return rng;
32  }
std::string Botan::HMAC_RNG::name ( ) const
virtual

Return the name of this object

Implements Botan::RandomNumberGenerator.

Definition at line 208 of file hmac_rng.cpp.

Referenced by randomize().

209  {
210  return "HMAC_RNG(" + m_extractor->name() + "," + m_prf->name() + ")";
211  }
byte Botan::RandomNumberGenerator::next_byte ( )
inlineinherited

Return a random byte

Returns
random byte

Definition at line 59 of file rng.h.

Referenced by Botan::random_prime().

60  {
61  byte out;
62  this->randomize(&out, 1);
63  return out;
64  }
virtual void randomize(byte output[], size_t length)=0
uint8_t byte
Definition: types.h:30
virtual secure_vector<byte> Botan::RandomNumberGenerator::random_vec ( size_t  bytes)
inlinevirtualinherited

Return a random vector

Parameters
bytesnumber of bytes in the result
Returns
randomized vector of length bytes

Definition at line 48 of file rng.h.

Referenced by Botan::TLS::Client_Key_Exchange::Client_Key_Exchange(), Botan::CryptoBox::encrypt(), Botan::KeyPair::encryption_consistency_check(), Botan::generate_bcrypt(), Botan::OctetString::OctetString(), Botan::pbes2_encrypt(), Botan::BigInt::randomize(), Botan::TLS::Session_Manager_SQLite::Session_Manager_SQLite(), and Botan::KeyPair::signature_consistency_check().

49  {
50  secure_vector<byte> output(bytes);
51  randomize(&output[0], output.size());
52  return output;
53  }
virtual void randomize(byte output[], size_t length)=0
void Botan::HMAC_RNG::randomize ( byte  output[],
size_t  length 
)
virtual

Randomize a byte array.

Parameters
outputthe byte array to hold the random output.
lengththe length of the byte array output.

Implements Botan::RandomNumberGenerator.

Definition at line 87 of file hmac_rng.cpp.

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

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  m_output_since_reseed += length;
99 
100  if(m_output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
101  reseed(BOTAN_RNG_RESEED_POLL_BITS);
102 
103  /*
104  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
105  */
106  while(length)
107  {
108  hmac_prf(*m_prf, m_K, m_counter, "rng");
109 
110  const size_t copied = std::min<size_t>(length, max_per_prf_iter);
111 
112  copy_mem(out, &m_K[0], copied);
113  out += copied;
114  length -= copied;
115  }
116  }
std::string name() const
Definition: hmac_rng.cpp:208
void reseed(size_t poll_bits)
Definition: hmac_rng.cpp:121
bool is_seeded() const
Definition: hmac_rng.cpp:179
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:39
void Botan::HMAC_RNG::reseed ( size_t  bits_to_collect)
virtual

Seed this RNG using the entropy sources it contains.

Parameters
bits_to_collectis the number of bits of entropy to attempt to gather from the entropy sources

Implements Botan::RandomNumberGenerator.

Definition at line 121 of file hmac_rng.cpp.

References Botan::Global_State_Management::global_state(), Botan::Library_State::poll_available_sources(), and Botan::zeroise().

Referenced by add_entropy(), and randomize().

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  }
Library_State & global_state()
uint8_t byte
Definition: types.h:30
void poll_available_sources(class Entropy_Accumulator &accum)
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:166

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