diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/lib/rng/auto_rng/auto_rng.h | 35 | ||||
| -rw-r--r-- | src/lib/rng/hmac_drbg/hmac_drbg.h | 15 | ||||
| -rw-r--r-- | src/lib/rng/rdrand_rng/rdrand_rng.h | 3 | ||||
| -rw-r--r-- | src/lib/rng/rng.h | 18 | ||||
| -rw-r--r-- | src/lib/rng/stateful_rng/stateful_rng.h | 20 | ||||
| -rw-r--r-- | src/lib/rng/system_rng/system_rng.h | 2 |
6 files changed, 82 insertions, 11 deletions
diff --git a/src/lib/rng/auto_rng/auto_rng.h b/src/lib/rng/auto_rng/auto_rng.h index 6ef1aa291..9ae9b9c38 100644 --- a/src/lib/rng/auto_rng/auto_rng.h +++ b/src/lib/rng/auto_rng/auto_rng.h @@ -27,6 +27,9 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator bool is_seeded() const override; + /** + * Mark state as requiring a reseed on next use + */ void force_reseed(); size_t reseed(Entropy_Sources& srcs, @@ -40,18 +43,44 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator void clear() override; /** - * If no RNG or entropy sources are provided to AutoSeeded_RNG, it uses the system RNG - * (if available) or else a default group of entropy sources (all other systems) to - * gather seed material. + * Uses the system RNG (if available) or else a default group of + * entropy sources (all other systems) to gather seed material. + * + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed */ AutoSeeded_RNG(size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param underlying_rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(RandomNumberGenerator& underlying_rng, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); + /** + * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material. + * + * @param underlying_rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ AutoSeeded_RNG(RandomNumberGenerator& underlying_rng, Entropy_Sources& entropy_sources, size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL); diff --git a/src/lib/rng/hmac_drbg/hmac_drbg.h b/src/lib/rng/hmac_drbg/hmac_drbg.h index 4f96af816..11d355d70 100644 --- a/src/lib/rng/hmac_drbg/hmac_drbg.h +++ b/src/lib/rng/hmac_drbg/hmac_drbg.h @@ -36,10 +36,14 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p underlying_rng will take place after + * @p reseed_interval many requests or after a fork was detected. + * + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding * @param reseed_interval specifies a limit of how many times - * the RNG will be called before automatic reseeding is performed. + * the RNG will be called before automatic reseeding is performed */ HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf, RandomNumberGenerator& underlying_rng, @@ -48,6 +52,10 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p entropy_sources will take place after + * @p reseed_interval many requests or after a fork was detected. + * + * @param prf MAC to use as a PRF * @param entropy_sources will be polled to perform reseeding periodically * @param reseed_interval specifies a limit of how many times * the RNG will be called before automatic reseeding is performed. @@ -59,6 +67,11 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG /** * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC) * + * Automatic reseeding from @p underlying_rng and @p entropy_sources + * will take place after @p reseed_interval many requests or after + * a fork was detected. + * + * @param prf MAC to use as a PRF * @param underlying_rng is a reference to some RNG which will be used * to perform the periodic reseeding * @param entropy_sources will be polled to perform reseeding periodically diff --git a/src/lib/rng/rdrand_rng/rdrand_rng.h b/src/lib/rng/rdrand_rng/rdrand_rng.h index fcd54035b..94363b89c 100644 --- a/src/lib/rng/rdrand_rng/rdrand_rng.h +++ b/src/lib/rng/rdrand_rng/rdrand_rng.h @@ -45,6 +45,9 @@ class BOTAN_DLL RDRAND_RNG : public Hardware_RNG void add_entropy(const uint8_t[], size_t) override { /* no op */ } + /* + * No way to reseed RDRAND generator, so reseed is ignored + */ size_t reseed(Entropy_Sources&, size_t, std::chrono::milliseconds) override { return 0; /* no op */ } diff --git a/src/lib/rng/rng.h b/src/lib/rng/rng.h index e3640a32f..36a423eca 100644 --- a/src/lib/rng/rng.h +++ b/src/lib/rng/rng.h @@ -38,7 +38,7 @@ class BOTAN_DLL RandomNumberGenerator /** * Randomize a byte array. * @param output the byte array to hold the random output. - * @param length the length of the byte array output. + * @param length the length of the byte array output in bytes. */ virtual void randomize(byte output[], size_t length) = 0; @@ -70,7 +70,12 @@ class BOTAN_DLL RandomNumberGenerator * Use this to further bind the outputs to your current * process/protocol state. For instance if generating a new key * for use in a session, include a session ID or other such - * value. See NIST SP 800-90 A, B, C series for more ideas. + * value. See NIST SP 800-90 A, B, C series for more ideas. + * + * @param output buffer to hold the random output + * @param output_len size of the output buffer in bytes + * @param input entropy buffer to incorporate + * @param input_len size of the input buffer in bytes */ virtual void randomize_with_input(byte output[], size_t output_len, const byte input[], size_t input_len); @@ -78,8 +83,8 @@ class BOTAN_DLL RandomNumberGenerator /** * This calls `randomize_with_input` using some timestamps as extra input. * - * For a stateful RNG using non-random but potentially unique data as the - * additional_input can help protect against problems with fork, VM state + * For a stateful RNG using non-random but potentially unique data the + * extra input can help protect against problems with fork, VM state * rollback, or other cases where somehow an RNG state is duplicated. If * both of the duplicated RNG states later incorporate a timestamp (and the * timestamps don't themselves repeat), their outputs will diverge. @@ -87,7 +92,7 @@ class BOTAN_DLL RandomNumberGenerator virtual void randomize_with_ts_input(byte output[], size_t output_len); /** - * Return the name of this RNG type + * @return the name of this RNG type */ virtual std::string name() const = 0; @@ -143,6 +148,9 @@ class BOTAN_DLL RandomNumberGenerator return b; } + /** + * @return a random byte that is not the zero byte + */ byte next_nonzero_byte() { byte b = this->next_byte(); diff --git a/src/lib/rng/stateful_rng/stateful_rng.h b/src/lib/rng/stateful_rng/stateful_rng.h index 11f0c7e3d..4eed85d0d 100644 --- a/src/lib/rng/stateful_rng/stateful_rng.h +++ b/src/lib/rng/stateful_rng/stateful_rng.h @@ -25,6 +25,13 @@ namespace Botan { class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator { public: + /** + * @param rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(RandomNumberGenerator& rng, Entropy_Sources& entropy_sources, size_t reseed_interval) : @@ -33,11 +40,22 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator m_reseed_interval(reseed_interval) {} + /** + * @param underlying_rng is a reference to some RNG which will be used + * to perform the periodic reseeding + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(RandomNumberGenerator& rng, size_t reseed_interval) : m_underlying_rng(&rng), m_reseed_interval(reseed_interval) {} + /** + * @param entropy_sources will be polled to perform reseeding periodically + * @param reseed_interval specifies a limit of how many times + * the RNG will be called before automatic reseeding is performed + */ Stateful_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval) : m_entropy_sources(&entropy_sources), m_reseed_interval(reseed_interval) @@ -81,7 +99,7 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator std::chrono::milliseconds poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT) override; /** - * Return intended security level of this DRBG + * @return intended security level of this DRBG */ virtual size_t security_level() const = 0; diff --git a/src/lib/rng/system_rng/system_rng.h b/src/lib/rng/system_rng/system_rng.h index 9cf31e78b..a31bb1dba 100644 --- a/src/lib/rng/system_rng/system_rng.h +++ b/src/lib/rng/system_rng/system_rng.h @@ -20,7 +20,7 @@ namespace Botan { BOTAN_DLL RandomNumberGenerator& system_rng(); /* -* Instantiatable reference to the system RNG. +* Instantiable reference to the system RNG. */ class BOTAN_DLL System_RNG final : public RandomNumberGenerator { |