pub struct JitterRng { /* private fields */ }
Expand description
A true random number generator based on jitter in the CPU execution time, and jitter in memory access time.
This is a true random number generator, as opposed to pseudo-random
generators. Random numbers generated by JitterRng
can be seen as fresh
entropy. A consequence is that is orders of magnitude slower than OsRng
and PRNGs (about 10^3 .. 10^6 slower).
There are very few situations where using this RNG is appropriate. Only very few applications require true entropy. A normal PRNG can be statistically indistinguishable, and a cryptographic PRNG should also be as impossible to predict.
Use of JitterRng
is recommended for initializing cryptographic PRNGs when
OsRng
is not available.
This implementation is based on Jitterentropy version 2.1.0.
Implementations
sourceimpl JitterRng
impl JitterRng
sourcepub fn new() -> Result<JitterRng, TimerError>
pub fn new() -> Result<JitterRng, TimerError>
Create a new JitterRng
.
Makes use of std::time
for a timer.
During initialization CPU execution timing jitter is measured a few hundred times. If this does not pass basic quality tests, an error is returned. The test result is cached to make subsequent calls faster.
sourcepub fn new_with_timer(timer: fn() -> u64) -> JitterRng
pub fn new_with_timer(timer: fn() -> u64) -> JitterRng
Create a new JitterRng
.
A custom timer can be supplied, making it possible to use JitterRng
in
no_std
environments.
The timer must have nanosecond precision.
This method is more low-level than new()
. It is the responsibility of
the caller to run test_timer
before using any numbers generated with
JitterRng
, and optionally call set_rounds()
.
sourcepub fn set_rounds(&mut self, rounds: u32)
pub fn set_rounds(&mut self, rounds: u32)
Configures how many rounds are used to generate each 64-bit value. This must be greater than zero, and has a big impact on performance and output quality.
new_with_timer
conservatively uses 64 rounds, but often less rounds
can be used. The test_timer()
function returns the minimum number of
rounds required for full strength (platform dependent), so one may use
rng.set_rounds(rng.test_timer()?);
or cache the value.
sourcepub fn test_timer(&mut self) -> Result<u32, TimerError>
pub fn test_timer(&mut self) -> Result<u32, TimerError>
Basic quality tests on the timer, by measuring CPU timing jitter a few hundred times.
If succesful, this will return the estimated number of rounds necessary
to collect 64 bits of entropy. Otherwise a TimerError
with the cause
of the failure will be returned.
sourcepub fn timer_stats(&mut self, var_rounds: bool) -> i64
pub fn timer_stats(&mut self, var_rounds: bool) -> i64
Statistical test: return the timer delta of one normal run of the
JitterEntropy
entropy collector.
Setting var_rounds
to true
will execute the memory access and the
CPU jitter noice sources a variable amount of times (just like a real
JitterEntropy
round).
Setting var_rounds
to false
will execute the noice sources the
minimal number of times. This can be used to measure the minimum amount
of entropy one round of entropy collector can collect in the worst case.
Example
Use timer_stats
to run the [NIST SP 800-90B Entropy Estimation Suite]
(https://github.com/usnistgov/SP800-90B_EntropyAssessment).
This is the recommended way to test the quality of JitterRng
. It
should be run before using the RNG on untested hardware, after changes
that could effect how the code is optimised, and after major compiler
compiler changes, like a new LLVM version.
First generate two files jitter_rng_var.bin
and jitter_rng_var.min
.
Execute python noniid_main.py -v jitter_rng_var.bin 8
, and validate it
with restart.py -v jitter_rng_var.bin 8 <min-entropy>
.
This number is the expected amount of entropy that is at least available
for each round of the entropy collector. This number should be greater
than the amount estimated with 64 / test_timer()
.
Execute python noniid_main.py -v -u 4 jitter_rng_var.bin 4
, and
validate it with restart.py -v -u 4 jitter_rng_var.bin 4 <min-entropy>
.
This number is the expected amount of entropy that is available in the
last 4 bits of the timer delta after running noice sources. Note that
a value of 3.70 is the minimum estimated entropy for true randomness.
Execute python noniid_main.py -v -u 4 jitter_rng_var.bin 4
, and
validate it with restart.py -v -u 4 jitter_rng_var.bin 4 <min-entropy>
.
This number is the expected amount of entropy that is available to the
entropy collecter if both noice sources only run their minimal number of
times. This measures the absolute worst-case, and gives a lower bound
for the available entropy.
use rand::JitterRng;
fn get_nstime() -> u64 {
use std::time::{SystemTime, UNIX_EPOCH};
let dur = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
// The correct way to calculate the current time is
// `dur.as_secs() * 1_000_000_000 + dur.subsec_nanos() as u64`
// But this is faster, and the difference in terms of entropy is
// negligible (log2(10^9) == 29.9).
dur.as_secs() << 30 | dur.subsec_nanos() as u64
}
// Do not initialize with `JitterRng::new`, but with `new_with_timer`.
// 'new' always runst `test_timer`, and can therefore fail to
// initialize. We want to be able to get the statistics even when the
// timer test fails.
let mut rng = JitterRng::new_with_timer(get_nstime);
// 1_000_000 results are required for the NIST SP 800-90B Entropy
// Estimation Suite
// FIXME: this number is smaller here, otherwise the Doc-test is too slow
const ROUNDS: usize = 10_000;
let mut deltas_variable: Vec<u8> = Vec::with_capacity(ROUNDS);
let mut deltas_minimal: Vec<u8> = Vec::with_capacity(ROUNDS);
for _ in 0..ROUNDS {
deltas_variable.push(rng.timer_stats(true) as u8);
deltas_minimal.push(rng.timer_stats(false) as u8);
}
// Write out after the statistics collection loop, to not disturb the
// test results.
File::create("jitter_rng_var.bin")?.write(&deltas_variable)?;
File::create("jitter_rng_min.bin")?.write(&deltas_minimal)?;
Trait Implementations
sourceimpl Rng for JitterRng
impl Rng for JitterRng
sourcefn fill_bytes(&mut self, dest: &mut [u8])
fn fill_bytes(&mut self, dest: &mut [u8])
dest
with random data. Read moresourcefn next_f32(&mut self) -> f32
fn next_f32(&mut self) -> f32
[0, 1)
. Read moresourcefn next_f64(&mut self) -> f64
fn next_f64(&mut self) -> f64
[0, 1)
. Read moresourcefn gen<T: Rand>(&mut self) -> Twhere
Self: Sized,
fn gen<T: Rand>(&mut self) -> Twhere
Self: Sized,
Rand
type. Read moresourcefn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> ⓘwhere
Self: Sized,
fn gen_iter<'a, T: Rand>(&'a mut self) -> Generator<'a, T, Self> ⓘwhere
Self: Sized,
sourcefn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> Twhere
Self: Sized,
fn gen_range<T: PartialOrd + SampleRange>(&mut self, low: T, high: T) -> Twhere
Self: Sized,
sourcefn gen_weighted_bool(&mut self, n: u32) -> boolwhere
Self: Sized,
fn gen_weighted_bool(&mut self, n: u32) -> boolwhere
Self: Sized,
sourcefn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> ⓘwhere
Self: Sized,
fn gen_ascii_chars<'a>(&'a mut self) -> AsciiGenerator<'a, Self> ⓘwhere
Self: Sized,
sourcefn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>where
Self: Sized,
fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>where
Self: Sized,
values
. Read more