aboutsummaryrefslogtreecommitdiffstats
path: root/src/lib
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib')
-rw-r--r--src/lib/rng/auto_rng/auto_rng.h35
-rw-r--r--src/lib/rng/hmac_drbg/hmac_drbg.h15
-rw-r--r--src/lib/rng/rdrand_rng/rdrand_rng.h3
-rw-r--r--src/lib/rng/rng.h18
-rw-r--r--src/lib/rng/stateful_rng/stateful_rng.h20
-rw-r--r--src/lib/rng/system_rng/system_rng.h2
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
{
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-18 05:11:46 +0000