Botan 3.14.1
Crypto and TLS for C&
chacha_rng.h
Go to the documentation of this file.
1/*
2* ChaCha_RNG
3* (C) 2017 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_CHACHA_RNG_H_
9#define BOTAN_CHACHA_RNG_H_
10
11#include <botan/mac.h>
12#include <botan/stateful_rng.h>
13#include <botan/stream_cipher.h>
14
15namespace Botan {
16
17class Entropy_Sources;
18
19/**
20* ChaCha_RNG is a very fast but completely ad-hoc RNG created by
21* creating a 256-bit random value and using it as a key for ChaCha20.
22*
23* The RNG maintains a 512-bit and a 256-bit key, one for HMAC_SHA512 (HK)
24* and the other for ChaCha20 (CK). To compute a new key in response to
25* reseeding request or add_entropy calls, ChaCha_RNG computes
26* CK' = HMAC_SHA512(HK, input_material)
27* Then a new HK' is computed by running ChaCha20 with the new key to
28* output 32 bytes:
29* HK' = ChaCha20(CK')
30*
31* Now output can be produced by continuing to produce output with ChaCha20
32* under CK'
33*
34* If fast key erasure rekeying is set in the constructor, CK gets overwritten
35* by additional output from ChaCha20 after each generate operation.
36* CK' = ChaCha20(CK)
37* This costs performance, but can be used when backtracking resistance
38* of the internal state is desired (e.g. for usage in DRG.3 or DRT.1
39* context of the German AIS 20/31 scheme).
40*
41* The first HK (before seeding occurs) is taken as the all zero value.
42*
43* @warning This RNG construction is probably fine but is non-standard.
44* The primary reason to use it is in cases where the other RNGs are
45* not fast enough.
46*
47* # Short rationale of design choices:
48* - (re-)seeding with HMAC(SHA-512) has the advantage, that inputs
49* do not need to have a fixed length and full entropy over a uniform
50* distribution, they just need to contain enough entropy (e.g. more
51* than 240 bit min-entropy). Using SHA-512 over SHA-256 as the underlying
52* primitive has the advantage of a wider internal width and less
53* entropy loss when hashing.
54* - Using ChaCha as stream cipher has the advantage of no entropy loss
55* regarding its seed due to being a random permutation for each key.
56* Furthermore ChaCha has a 512 bit block width, which shifts block
57* collisions in a very unlikely range (regarding output block count).
58* - Using ChaCha(20) instead of ChaCha(8) or ChaCha(12) has the
59* advantage of being a conservative choice also taken by the
60* Linux kernel, where it is already accepted as a secure CSPRNG
61* implementation by many people and organizations.
62* - Providing optional fast key erasure is necessary to reach
63* backtracking resistance of the internal state. This costs
64* performance depending on the request sizes of the user.
65* It's of course more expensive to rekey on every 4 byte output,
66* than let's say 1024 byte buffers.
67* Because of these performance reasons, it has to be enabled explicitly.
68* - Also set nonce/IV of ChaCha when (re-)seeding and rekeying, to effectively
69* extend effective internal high entropy state by 64 bit.
70*/
71class BOTAN_PUBLIC_API(2, 3) ChaCha_RNG final : public Stateful_RNG {
72 private: // constants
73 static constexpr std::string_view stream_cipher_algo = "ChaCha(20)";
74 static constexpr std::string_view hmac_algo = "HMAC(SHA-512)";
75
76 // use maximum key length providing 256 bit security
77 static constexpr size_t chacha_key_len = 32;
78 // use "classic" 8 byte nonce as extended key material
79 static constexpr size_t chacha_iv_len = 8;
80
81 public:
82 enum class KeyErasure : uint8_t { NoErasure, WithKeyErasure };
83
84 /**
85 * Automatic reseeding is disabled completely, as it has no access to
86 * any source for seed material.
87 *
88 * If a fork is detected, the RNG will be unable to reseed itself
89 * in response. In this case, an exception will be thrown rather
90 * than generating duplicated output.
91 *
92 * @param key_erasure overwrite state after each operation
93 * for backtracking resistance, costs performance depending
94 * on request size mix, deactivated by default
95 */
96 explicit ChaCha_RNG(KeyErasure key_erasure = KeyErasure::NoErasure);
97
98 /**
99 * Provide an initial seed to the RNG, without providing an
100 * underlying RNG or entropy source. Automatic reseeding is
101 * disabled completely, as it has no access to any source for
102 * seed material.
103 *
104 * If a fork is detected, the RNG will be unable to reseed itself
105 * in response. In this case, an exception will be thrown rather
106 * than generating duplicated output.
107 *
108 * @param seed the seed material, should be at least 256 bits
109 * @param key_erasure overwrite state after each operation
110 * for backtracking resistance, costs performance depending
111 * on request size mix, deactivated by default
112 */
113 BOTAN_FUTURE_EXPLICIT ChaCha_RNG(std::span<const uint8_t> seed, KeyErasure key_erasure = KeyErasure::NoErasure);
114
115 /**
116 * Automatic reseeding from @p underlying_rng will take place after
117 * @p reseed_interval many requests or after a fork was detected.
118 *
119 * @param underlying_rng is a reference to some RNG which will be used
120 * to perform the periodic reseeding
121 * @param reseed_interval specifies a limit of how many times
122 * the RNG will be called before automatic reseeding is performed
123 * @param key_erasure overwrite state after each operation
124 * for backtracking resistance, costs performance depending
125 * on request size mix, deactivated by default
126 */
128 size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval,
129 KeyErasure key_erasure = KeyErasure::NoErasure);
130
131 /**
132 * Automatic reseeding from @p entropy_sources will take place after
133 * @p reseed_interval many requests or after a fork was detected.
134 *
135 * @param entropy_sources will be polled to perform reseeding periodically
136 * @param reseed_interval specifies a limit of how many times
137 * the RNG will be called before automatic reseeding is performed.
138 * @param key_erasure overwrite state after each operation
139 * for backtracking resistance, costs performance depending
140 * on request size mix, deactivated by default
141 */
143 size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval,
144 KeyErasure key_erasure = KeyErasure::NoErasure);
145
146 /**
147 * Automatic reseeding from @p underlying_rng and @p entropy_sources
148 * will take place after @p reseed_interval many requests or after
149 * a fork was detected.
150 *
151 * @param underlying_rng is a reference to some RNG which will be used
152 * to perform the periodic reseeding
153 * @param entropy_sources will be polled to perform reseeding periodically
154 * @param reseed_interval specifies a limit of how many times
155 * the RNG will be called before automatic reseeding is performed.
156 * @param key_erasure overwrite state after each operation
157 * for backtracking resistance, costs performance depending
158 * on request size mix, deactivated by default
159 */
160 ChaCha_RNG(RandomNumberGenerator& underlying_rng,
161 Entropy_Sources& entropy_sources,
162 size_t reseed_interval = RandomNumberGenerator::DefaultReseedInterval,
163 KeyErasure key_erasure = KeyErasure::NoErasure);
164
165 /**
166 * Return the name of this RNG type
167 * @return the name of this RNG type
168 */
169 std::string name() const override { return "ChaCha_RNG"; }
170
171 /**
172 * Return the security level of this DRBG
173 * @return the estimated security level in bits
174 */
175 size_t security_level() const override;
176
177 /**
178 * Return the largest number of bytes this DRBG will produce per request
179 * @return 2^{16} with key erasure (BSI's AIs 20/31 3.0 DRG.3.2 limits a
180 * request to 2^{19} bits.), otherwise zero (no limit)
181 */
182 size_t max_number_of_bytes_per_request() const override {
183 return (m_key_erasure == KeyErasure::WithKeyErasure ? 65536 : 0);
184 }
185
186 KeyErasure key_erasure() const { return m_key_erasure; }
187
188 private:
189 void update(std::span<const uint8_t> input) override;
190
191 void generate_output(std::span<uint8_t> output, std::span<const uint8_t> input) override;
192
193 void clear_state() override;
194
195 void update_chacha_state(std::span<const uint8_t> key_material);
196
197 std::unique_ptr<MessageAuthenticationCode> m_hmac;
198 std::unique_ptr<StreamCipher> m_chacha;
199 KeyErasure m_key_erasure;
200};
201
202} // namespace Botan
203
204#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
size_t max_number_of_bytes_per_request() const override
Definition chacha_rng.h:182
KeyErasure key_erasure() const
Definition chacha_rng.h:186
ChaCha_RNG(KeyErasure key_erasure=KeyErasure::NoErasure)
std::string name() const override
Definition chacha_rng.h:169
static constexpr size_t DefaultReseedInterval
Definition rng.h:45
Stateful_RNG(RandomNumberGenerator &rng, Entropy_Sources &entropy_sources, size_t reseed_interval)