Botan 2.19.5 Crypto and TLS for C&

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*/
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 { 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
Botan::Entropy_Sources
Definition: entropy_src.h:57
Botan::HMAC_DRBG
Definition: hmac_drbg.h:22
Botan::HMAC_DRBG::max_number_of_bytes_per_request
size_t max_number_of_bytes_per_request() const override
Definition: hmac_drbg.h:131
Botan::RandomNumberGenerator
Definition: rng.h:26
Botan::Stateful_RNG
Definition: stateful_rng.h:27
name
std::string name
Definition: commoncrypto_hash.cpp:24
update
int(* update)(CTX *, const void *, CC_LONG len)
Definition: commoncrypto_hash.cpp:28
final
int(* final)(unsigned char *, CTX *)
Definition: commoncrypto_hash.cpp:29
BOTAN_PUBLIC_API
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Botan
Definition: alg_id.cpp:13
Botan::secure_vector
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65