|
virtual bool | accepts_input () const =0 |
|
void | add_entropy (const uint8_t input[], size_t length) |
|
void | add_entropy (std::span< const uint8_t > input) |
|
template<typename T >
requires std::is_standard_layout<T>::value && std::is_trivial<T>::value |
void | add_entropy_T (const T &t) |
|
virtual void | clear ()=0 |
|
virtual bool | is_seeded () const =0 |
|
virtual std::string | name () const =0 |
|
uint8_t | next_byte () |
|
uint8_t | next_nonzero_byte () |
|
RandomNumberGenerator & | operator= (const RandomNumberGenerator &rng)=delete |
|
template<size_t bytes> |
std::array< uint8_t, bytes > | random_array () |
|
template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
requires std::default_initializable<T> |
T | random_vec (size_t bytes) |
|
void | random_vec (std::span< uint8_t > v) |
|
template<concepts::resizable_byte_buffer T> |
void | random_vec (T &v, size_t bytes) |
|
void | randomize (std::span< uint8_t > output) |
|
void | randomize (uint8_t output[], size_t length) |
|
void | randomize_with_input (std::span< uint8_t > output, std::span< const uint8_t > input) |
|
void | randomize_with_input (uint8_t output[], size_t output_len, const uint8_t input[], size_t input_len) |
|
void | randomize_with_ts_input (std::span< uint8_t > output) |
|
void | randomize_with_ts_input (uint8_t output[], size_t output_len) |
|
| RandomNumberGenerator ()=default |
|
| RandomNumberGenerator (const RandomNumberGenerator &rng)=delete |
|
virtual size_t | reseed (Entropy_Sources &srcs, size_t poll_bits=BOTAN_RNG_RESEED_POLL_BITS, std::chrono::milliseconds poll_timeout=BOTAN_RNG_RESEED_DEFAULT_TIMEOUT) |
|
virtual void | reseed_from_rng (RandomNumberGenerator &rng, size_t poll_bits=BOTAN_RNG_RESEED_POLL_BITS) |
|
virtual | ~RandomNumberGenerator ()=default |
|
An interface to a cryptographic random number generator
Definition at line 30 of file rng.h.
virtual bool Botan::RandomNumberGenerator::accepts_input |
( |
| ) |
const |
|
pure virtual |
Returns false if it is known that this RNG object is not able to accept externally provided inputs (via add_entropy, randomize_with_input, etc). In this case, any such provided inputs are ignored.
If this function returns true, then inputs may or may not be accepted.
Implemented in Botan::AutoSeeded_RNG, Botan::Null_RNG, Botan::PKCS11::PKCS11_RNG, Botan::Processor_RNG, Botan::Stateful_RNG, Botan::System_RNG, and Botan::TPM_RNG.
Referenced by Botan::System_RNG::accepts_input(), randomize_with_ts_input(), reseed(), and reseed_from_rng().
virtual void Botan::RandomNumberGenerator::fill_bytes_with_input |
( |
std::span< uint8_t > | output, |
|
|
std::span< const uint8_t > | input ) |
|
protectedpure virtual |
Generic interface to provide entropy to a concrete implementation and to fill a given buffer with random output. Both output
and input
may be empty and should be ignored in that case. If both buffers are non-empty implementations should typically first apply the input
data and then generate random data into output
.
This method must be implemented by all RandomNumberGenerator sub-classes.
- Parameters
-
output | Byte buffer to write random bytes into. Implementations should not read from this buffer. |
input | Byte buffer that may contain bytes to be incorporated in the RNG's internal state. Implementations may choose to ignore the bytes in this buffer. |
Implemented in Botan::System_RNG.
Referenced by randomize_with_ts_input().
void Botan::RandomNumberGenerator::randomize_with_input |
( |
std::span< uint8_t > | output, |
|
|
std::span< const uint8_t > | input ) |
|
inline |
Incorporate entropy into the RNG state then produce output. Some RNG types implement this using a single operation, default calls add_entropy + randomize in sequence.
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.
- Parameters
-
output | buffer to hold the random output |
input | entropy buffer to incorporate |
- Exceptions
-
PRNG_Unseeded | if the RNG fails because it has not enough entropy |
Exception | if the RNG fails |
Exception | may throw if the RNG accepts input, but adding the entropy failed. |
Definition at line 104 of file rng.h.
Referenced by Botan::System_RNG::fill_bytes_with_input().
void Botan::RandomNumberGenerator::randomize_with_ts_input |
( |
std::span< uint8_t > | output | ) |
|
This calls randomize_with_input
using some timestamps as extra input.
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.
- Parameters
-
output | buffer to hold the random output |
- Exceptions
-
PRNG_Unseeded | if the RNG fails because it has not enough entropy |
Exception | if the RNG fails |
Exception | may throw if the RNG accepts input, but adding the entropy failed. |
Definition at line 21 of file rng.cpp.
21 {
26
27 std::array<uint8_t, s_hd_clk + s_sys_ts + s_pid> additional_input = {0};
28 auto s_additional_input = std::span(additional_input.begin(), additional_input.end());
29
31 s_additional_input = s_additional_input.subspan(s_hd_clk);
32
33#if defined(BOTAN_HAS_SYSTEM_RNG)
36#else
38 s_additional_input = s_additional_input.subspan(s_sys_ts);
39
41#endif
42
44 } else {
46 }
47}
virtual bool accepts_input() const =0
uint64_t BOTAN_TEST_API get_high_resolution_clock()
uint64_t BOTAN_TEST_API get_system_timestamp_ns()
uint32_t BOTAN_TEST_API get_process_id()
RandomNumberGenerator & system_rng()
constexpr auto store_le(ParamTs &&... params)
References accepts_input(), fill_bytes_with_input(), Botan::OS::get_high_resolution_clock(), Botan::OS::get_process_id(), Botan::OS::get_system_timestamp_ns(), randomize(), Botan::store_le(), and Botan::system_rng().