/src/botan/build/include/botan/hmac_drbg.h
Line | Count | Source (jump to first uncovered line) |
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 | | */ |
21 | | class BOTAN_PUBLIC_API(2,0) HMAC_DRBG final : public Stateful_RNG |
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 | 0 | { 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; |
143 | | secure_vector<uint8_t> m_V; |
144 | | const size_t m_max_number_of_bytes_per_request; |
145 | | const size_t m_security_level; |
146 | | }; |
147 | | |
148 | | } |
149 | | |
150 | | #endif |