Botan  1.11.30
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) override
 
void clear () override
 
template<typename T >
get_random ()
 
 HMAC_RNG (MessageAuthenticationCode *extractor, MessageAuthenticationCode *prf)
 
bool is_seeded () const override
 
std::string name () const override
 
byte next_byte ()
 
byte next_nonzero_byte ()
 
virtual secure_vector< byterandom_vec (size_t bytes)
 
void randomize (byte buf[], size_t len) override
 
size_t reseed (size_t bits_to_collect)
 
size_t reseed_with_sources (Entropy_Sources &srcs, size_t poll_bits, std::chrono::milliseconds poll_timeout) override
 
size_t reseed_with_timeout (size_t bits_to_collect, std::chrono::milliseconds poll_timeout)
 

Static Public Member Functions

static RandomNumberGeneratormake_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

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 19 of file hmac_rng.cpp.

References clear().

20  :
21  m_extractor(extractor), m_prf(prf)
22  {
23  if(!m_prf->valid_keylength(m_extractor->output_length()) ||
24  !m_extractor->valid_keylength(m_prf->output_length()))
25  {
26  throw Invalid_Argument("HMAC_RNG: Bad algo combination " +
27  m_extractor->name() + " and " +
28  m_prf->name());
29  }
30 
31  this->clear();
32  }
void clear() override
Definition: hmac_rng.cpp:34

Member Function Documentation

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

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 186 of file hmac_rng.cpp.

References Botan::Entropy_Sources::global_sources(), and reseed_with_sources().

187  {
188  m_extractor->update(input, length);
189 
191  BOTAN_RNG_RESEED_POLL_BITS,
192  BOTAN_RNG_RESEED_DEFAULT_TIMEOUT);
193  }
static Entropy_Sources & global_sources()
size_t reseed_with_sources(Entropy_Sources &srcs, size_t poll_bits, std::chrono::milliseconds poll_timeout) override
Definition: hmac_rng.cpp:120
void Botan::HMAC_RNG::clear ( )
overridevirtual

Clear all internally held values of this RNG.

Implements Botan::RandomNumberGenerator.

Definition at line 34 of file hmac_rng.cpp.

References Botan::OS::get_processor_timestamp(), Botan::OS::get_system_timestamp_ns(), and Botan::zeroise().

Referenced by HMAC_RNG().

35  {
36  m_collected_entropy_estimate = 0;
37  m_counter = 0;
38 
39  // First PRF inputs are all zero, as specified in section 2
40  m_K.resize(m_prf->output_length());
41  zeroise(m_K);
42 
43  /*
44  Normally we want to feedback PRF outputs to the extractor function
45  to ensure a single bad poll does not reduce entropy. Thus in reseed
46  we'll want to invoke the PRF before we reset the PRF key, but until
47  the first reseed the PRF is unkeyed. Rather than trying to keep
48  track of this, just set the initial PRF key to constant zero.
49  Since all PRF inputs in the first reseed are constants, this
50  amounts to suffixing the seed in the first poll with a fixed
51  constant string.
52 
53  The PRF key will not be used to generate outputs until after reseed
54  sets m_seeded to true.
55  */
56  std::vector<byte> prf_zero_key(m_extractor->output_length());
57  m_prf->set_key(prf_zero_key.data(), prf_zero_key.size());
58 
59  /*
60  Use PRF("Botan HMAC_RNG XTS") as the intitial XTS key.
61 
62  This will be used during the first extraction sequence; XTS values
63  after this one are generated using the PRF.
64 
65  If I understand the E-t-E paper correctly (specifically Section 4),
66  using this fixed initial extractor key is safe to do.
67  */
68  m_extractor->set_key(m_prf->process("Botan HMAC_RNG XTS"));
69  }
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:186
template<typename T >
T Botan::RandomNumberGenerator::get_random ( )
inlineinherited

Only usable with POD types, only useful with integers get_random<u64bit>()

Definition at line 56 of file rng.h.

57  {
58  T r;
59  this->randomize(reinterpret_cast<byte*>(&r), sizeof(r));
60  return r;
61  }
virtual void randomize(byte output[], size_t length)=0
bool Botan::HMAC_RNG::is_seeded ( ) const
overridevirtual

Check whether this RNG is seeded.

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

Implements Botan::RandomNumberGenerator.

Definition at line 177 of file hmac_rng.cpp.

Referenced by randomize().

178  {
179  return (m_collected_entropy_estimate >= 256);
180  }
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 28 of file rng.cpp.

References Botan::MessageAuthenticationCode::create().

29  {
30  std::unique_ptr<MessageAuthenticationCode> h1(MessageAuthenticationCode::create("HMAC(SHA-512)"));
31  std::unique_ptr<MessageAuthenticationCode> h2(MessageAuthenticationCode::create("HMAC(SHA-512)"));
32 
33  if(!h1 || !h2)
34  throw Algorithm_Not_Found("HMAC_RNG HMACs");
35  std::unique_ptr<RandomNumberGenerator> rng(new HMAC_RNG(h1.release(), h2.release()));
36 
37  rng->reseed(256);
38 
39  return rng.release();
40  }
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:38
std::string Botan::HMAC_RNG::name ( ) const
overridevirtual

Return the name of this object

Implements Botan::RandomNumberGenerator.

Definition at line 198 of file hmac_rng.cpp.

Referenced by randomize().

199  {
200  return "HMAC_RNG(" + m_extractor->name() + "," + m_prf->name() + ")";
201  }
byte Botan::RandomNumberGenerator::next_byte ( )
inlineinherited

Return a random byte

Returns
random byte

Definition at line 67 of file rng.h.

Referenced by Botan::Blinded_Point_Multiply::blinded_multiply(), and Botan::random_prime().

67 { return get_random<byte>(); }
byte Botan::RandomNumberGenerator::next_nonzero_byte ( )
inlineinherited

Definition at line 69 of file rng.h.

70  {
71  byte b = next_byte();
72  while(b == 0)
73  b = next_byte();
74  return b;
75  }
std::uint8_t byte
Definition: types.h:31
virtual secure_vector<byte> Botan::RandomNumberGenerator::random_vec ( size_t  bytes)
inlinevirtualinherited
void Botan::HMAC_RNG::randomize ( byte  output[],
size_t  length 
)
overridevirtual

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 85 of file hmac_rng.cpp.

References Botan::copy_mem(), Botan::OS::get_process_id(), Botan::Entropy_Sources::global_sources(), is_seeded(), name(), Botan::RandomNumberGenerator::reseed(), and reseed_with_sources().

86  {
87  if(!is_seeded() || m_pid != OS::get_process_id())
88  {
89  reseed(256);
90  if(!is_seeded())
91  throw PRNG_Unseeded(name());
92  }
93 
94  const size_t max_per_prf_iter = m_prf->output_length() / 2;
95 
96  m_output_since_reseed += length;
97 
98  if(m_output_since_reseed >= BOTAN_RNG_MAX_OUTPUT_BEFORE_RESEED)
99  {
101  BOTAN_RNG_RESEED_POLL_BITS,
102  BOTAN_RNG_AUTO_RESEED_TIMEOUT);
103  }
104 
105  /*
106  HMAC KDF as described in E-t-E, using a CTXinfo of "rng"
107  */
108  while(length)
109  {
110  new_K_value(Running);
111 
112  const size_t copied = std::min<size_t>(length, max_per_prf_iter);
113 
114  copy_mem(out, m_K.data(), copied);
115  out += copied;
116  length -= copied;
117  }
118  }
size_t reseed(size_t bits_to_collect)
Definition: rng.cpp:14
uint32_t get_process_id()
Definition: os_utils.cpp:30
std::string name() const override
Definition: hmac_rng.cpp:198
void copy_mem(T *out, const T *in, size_t n)
Definition: mem_ops.h:43
bool is_seeded() const override
Definition: hmac_rng.cpp:177
static Entropy_Sources & global_sources()
size_t reseed_with_sources(Entropy_Sources &srcs, size_t poll_bits, std::chrono::milliseconds poll_timeout) override
Definition: hmac_rng.cpp:120
size_t Botan::RandomNumberGenerator::reseed ( size_t  bits_to_collect)
inherited

Seed this RNG using the global entropy sources and default timeout

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

Definition at line 14 of file rng.cpp.

References Botan::RandomNumberGenerator::reseed_with_timeout().

Referenced by botan_rng_reseed(), Botan::ANSI_X931_RNG::randomize(), Botan::HMAC_DRBG::randomize(), and randomize().

15  {
16  return this->reseed_with_timeout(bits_to_collect,
17  BOTAN_RNG_RESEED_DEFAULT_TIMEOUT);
18  }
size_t reseed_with_timeout(size_t bits_to_collect, std::chrono::milliseconds poll_timeout)
Definition: rng.cpp:20
size_t Botan::HMAC_RNG::reseed_with_sources ( Entropy_Sources srcs,
size_t  poll_bits,
std::chrono::milliseconds  poll_timeout 
)
overridevirtual

Poll provided sources for up to poll_bits bits of entropy or until the timeout expires. Returns estimate of the number of bits collected.

Implements Botan::RandomNumberGenerator.

Definition at line 120 of file hmac_rng.cpp.

References Botan::OS::get_process_id(), Botan::Entropy_Sources::poll(), and Botan::zeroise().

Referenced by add_entropy(), and randomize().

123  {
124  /*
125  Using the terminology of E-t-E, XTR is the MAC function (normally
126  HMAC) seeded with XTS (below) and we form SKM, the key material, by
127  polling as many sources as we think needed to reach our polling
128  goal. We then also include feedback of the current PRK so that
129  a bad poll doesn't wipe us out.
130  */
131 
132  typedef std::chrono::system_clock clock;
133  auto deadline = clock::now() + timeout;
134 
135  double bits_collected = 0;
136 
137  Entropy_Accumulator accum([&](const byte in[], size_t in_len, double entropy_estimate) {
138  m_extractor->update(in, in_len);
139  bits_collected += entropy_estimate;
140  return (bits_collected >= poll_bits || clock::now() > deadline);
141  });
142 
143  srcs.poll(accum);
144 
145  /*
146  * It is necessary to feed forward poll data. Otherwise, a good poll
147  * (collecting a large amount of conditional entropy) followed by a
148  * bad one (collecting little) would be unsafe. Do this by
149  * generating new PRF outputs using the previous key and feeding
150  * them into the extractor function.
151  */
152  new_K_value(Reseed);
153  m_extractor->update(m_K); // K is the CTXinfo=reseed PRF output
154 
155  /* Now derive the new PRK using everything that has been fed into
156  the extractor, and set the PRF key to that */
157  m_prf->set_key(m_extractor->final());
158 
159  // Now generate a new PRF output to use as the XTS extractor salt
160  new_K_value(ExtractorSeed);
161  m_extractor->set_key(m_K);
162 
163  // Reset state
164  zeroise(m_K);
165  m_counter = 0;
166 
167  m_collected_entropy_estimate =
168  std::min<size_t>(m_collected_entropy_estimate + static_cast<size_t>(bits_collected),
169  m_extractor->output_length() * 8);
170 
171  m_output_since_reseed = 0;
172  m_pid = OS::get_process_id();
173 
174  return static_cast<size_t>(bits_collected);
175  }
uint32_t get_process_id()
Definition: os_utils.cpp:30
void zeroise(std::vector< T, Alloc > &vec)
Definition: secmem.h:186
std::uint8_t byte
Definition: types.h:31
size_t Botan::RandomNumberGenerator::reseed_with_timeout ( size_t  bits_to_collect,
std::chrono::milliseconds  poll_timeout 
)
inherited

Seed this RNG using the global entropy sources

Parameters
bits_to_collectis the number of bits of entropy to attempt to gather from the entropy sources
poll_timeouttry not to run longer than this, no matter what

Definition at line 20 of file rng.cpp.

References Botan::Entropy_Sources::global_sources(), and Botan::RandomNumberGenerator::reseed_with_sources().

Referenced by Botan::RandomNumberGenerator::reseed().

22  {
24  bits_to_collect,
25  timeout);
26  }
virtual size_t reseed_with_sources(Entropy_Sources &srcs, size_t poll_bits, std::chrono::milliseconds poll_timeout)=0
static Entropy_Sources & global_sources()

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