Botan  2.16.0
Crypto and TLS for C++11
hmac_drbg.h
Go to the documentation of this file.
1 /*
2 * HMAC_DRBG (SP800-90A)
3 * (C) 2014,2015,2016 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7 
8 #ifndef BOTAN_HMAC_DRBG_H_
9 #define BOTAN_HMAC_DRBG_H_
10 
11 #include <botan/stateful_rng.h>
12 #include <botan/mac.h>
13 
14 namespace Botan {
15 
16 class Entropy_Sources;
17 
18 /**
19 * HMAC_DRBG from NIST SP800-90A
20 */
22  {
23  public:
24  /**
25  * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
26  *
27  * Automatic reseeding is disabled completely, as it has no access to
28  * any source for seed material.
29  *
30  * If a fork is detected, the RNG will be unable to reseed itself
31  * in response. In this case, an exception will be thrown rather
32  * than generating duplicated output.
33  */
34  explicit HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf);
35 
36  /**
37  * Constructor taking a string for the hash
38  */
39  explicit HMAC_DRBG(const std::string& hmac_hash);
40 
41  /**
42  * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
43  *
44  * Automatic reseeding from @p underlying_rng will take place after
45  * @p reseed_interval many requests or after a fork was detected.
46  *
47  * @param prf MAC to use as a PRF
48  * @param underlying_rng is a reference to some RNG which will be used
49  * to perform the periodic reseeding
50  * @param reseed_interval specifies a limit of how many times
51  * the RNG will be called before automatic reseeding is performed (max. 2^24)
52  * @param max_number_of_bytes_per_request requests that are in size higher
53  * than max_number_of_bytes_per_request are treated as if multiple single
54  * requests of max_number_of_bytes_per_request size had been made.
55  * In theory SP 800-90A requires that we reject any request for a DRBG
56  * output longer than max_number_of_bytes_per_request. To avoid inconveniencing
57  * the caller who wants an output larger than max_number_of_bytes_per_request,
58  * instead treat these requests as if multiple requests of
59  * max_number_of_bytes_per_request size had been made. NIST requires for
60  * HMAC_DRBG that every implementation set a value no more than 2**19 bits
61  * (or 64 KiB). Together with @p reseed_interval = 1 you can enforce that for
62  * example every 512 bit automatic reseeding occurs.
63  */
64  HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf,
65  RandomNumberGenerator& underlying_rng,
66  size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL,
67  size_t max_number_of_bytes_per_request = 64 * 1024);
68 
69  /**
70  * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
71  *
72  * Automatic reseeding from @p entropy_sources will take place after
73  * @p reseed_interval many requests or after a fork was detected.
74  *
75  * @param prf MAC to use as a PRF
76  * @param entropy_sources will be polled to perform reseeding periodically
77  * @param reseed_interval specifies a limit of how many times
78  * the RNG will be called before automatic reseeding is performed (max. 2^24)
79  * @param max_number_of_bytes_per_request requests that are in size higher
80  * than max_number_of_bytes_per_request are treated as if multiple single
81  * requests of max_number_of_bytes_per_request size had been made.
82  * In theory SP 800-90A requires that we reject any request for a DRBG
83  * output longer than max_number_of_bytes_per_request. To avoid inconveniencing
84  * the caller who wants an output larger than max_number_of_bytes_per_request,
85  * instead treat these requests as if multiple requests of
86  * max_number_of_bytes_per_request size had been made. NIST requires for
87  * HMAC_DRBG that every implementation set a value no more than 2**19 bits
88  * (or 64 KiB). Together with @p reseed_interval = 1 you can enforce that for
89  * example every 512 bit automatic reseeding occurs.
90  */
91  HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf,
92  Entropy_Sources& entropy_sources,
93  size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL,
94  size_t max_number_of_bytes_per_request = 64 * 1024);
95 
96  /**
97  * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
98  *
99  * Automatic reseeding from @p underlying_rng and @p entropy_sources
100  * will take place after @p reseed_interval many requests or after
101  * a fork was detected.
102  *
103  * @param prf MAC to use as a PRF
104  * @param underlying_rng is a reference to some RNG which will be used
105  * to perform the periodic reseeding
106  * @param entropy_sources will be polled to perform reseeding periodically
107  * @param reseed_interval specifies a limit of how many times
108  * the RNG will be called before automatic reseeding is performed (max. 2^24)
109  * @param max_number_of_bytes_per_request requests that are in size higher
110  * than max_number_of_bytes_per_request are treated as if multiple single
111  * requests of max_number_of_bytes_per_request size had been made.
112  * In theory SP 800-90A requires that we reject any request for a DRBG
113  * output longer than max_number_of_bytes_per_request. To avoid inconveniencing
114  * the caller who wants an output larger than max_number_of_bytes_per_request,
115  * instead treat these requests as if multiple requests of
116  * max_number_of_bytes_per_request size had been made. NIST requires for
117  * HMAC_DRBG that every implementation set a value no more than 2**19 bits
118  * (or 64 KiB). Together with @p reseed_interval = 1 you can enforce that for
119  * example every 512 bit automatic reseeding occurs.
120  */
121  HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf,
122  RandomNumberGenerator& underlying_rng,
123  Entropy_Sources& entropy_sources,
124  size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL,
125  size_t max_number_of_bytes_per_request = 64 * 1024);
126 
127  std::string name() const override;
128 
129  size_t security_level() const override;
130 
131  size_t max_number_of_bytes_per_request() const override
132  { return m_max_number_of_bytes_per_request; }
133 
134  private:
135  void update(const uint8_t input[], size_t input_len) override;
136 
137  void generate_output(uint8_t output[], size_t output_len,
138  const uint8_t input[], size_t input_len) override;
139 
140  void clear_state() override;
141 
142  std::unique_ptr<MessageAuthenticationCode> m_mac;
144  const size_t m_max_number_of_bytes_per_request;
145  const size_t m_security_level;
146  };
147 
148 }
149 
150 #endif
int(* final)(unsigned char *, CTX *)
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
std::string name
size_t max_number_of_bytes_per_request() const override
Definition: hmac_drbg.h:131
Definition: alg_id.cpp:13
int(* update)(CTX *, const void *, CC_LONG len)
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65