Struct rand::rngs::JitterRng

pub struct JitterRng { /* fields omitted */ }

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³..10⁶ 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.

JitterRng can be used without the standard library, but not conveniently, you must provide a high-precision timer and carefully have to follow the instructions of new_with_timer.

This implementation is based on Jitterentropy version 2.1.0.

Note: There is no accurate timer available on Wasm platforms, to help prevent fingerprinting or timing side-channel attacks. Therefore JitterRng::new() is not available on Wasm.

Quality testing

JitterRng::new() has build-in, but limited, quality testing, however before using JitterRng on untested hardware, or after changes that could effect how the code is optimized (such as a new LLVM version), it is recommend to run the much more stringent NIST SP 800-90B Entropy Estimation Suite.

Use the following code using timer_stats to collect the data:

use rand::jitter::JitterRng;
let mut rng = JitterRng::new()?;

// 1_000_000 results are required for the
// NIST SP 800-90B Entropy Estimation Suite
const ROUNDS: usize = 1_000_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)?;

This will produce two files: jitter_rng_var.bin and jitter_rng_min.bin. Run the Entropy Estimation Suite in three configurations, as outlined below. Every run has two steps. One step to produce an estimation, another to validate the estimation.

1. Estimate the expected amount of entropy that is at least available with each round of the entropy collector. This number should be greater than the amount estimated with 64 / test_timer().

   python noniid_main.py -v jitter_rng_var.bin 8
   restart.py -v jitter_rng_var.bin 8 <min-entropy>
   

2. Estimate 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.

   python noniid_main.py -v -u 4 jitter_rng_var.bin 4
   restart.py -v -u 4 jitter_rng_var.bin 4 <min-entropy>
   

3. Estimate the expected amount of entropy that is available to the entropy collector 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.

   python noniid_main.py -v -u 4 jitter_rng_min.bin 4
   restart.py -v -u 4 jitter_rng_min.bin 4 <min-entropy>
   

Methods

impl JitterRng

pub fn new() -> Result<JitterRng, TimerError>

Create a new JitterRng. Makes use of std::time for a timer, or a platform-specific function with higher accuracy if necessary and available.

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.

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. Also it is important to consume at least one u64 before using the first result to initialize the entropy collection pool.

Example

use rand::jitter::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
}

let mut rng = JitterRng::new_with_timer(get_nstime);
let rounds = rng.test_timer()?;
rng.set_rounds(rounds); // optional
let _ = rng.gen::<u64>();

// Ready for use
let v: u64 = rng.gen();

pub fn set_rounds(&mut self, rounds: u8)

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.

pub fn test_timer(&mut self) -> Result<u8, 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.

pub fn timer_stats(&mut self, var_rounds: bool) -> i64

Statistical test: return the timer delta of one normal run of the JitterRng 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 JitterRng 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 the entropy collector can collect in the worst case.

See Quality testing on how to use timer_stats to test the quality of JitterRng.

Trait Implementations

impl Debug for JitterRng

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Clone for JitterRng

fn clone(&self) -> JitterRng

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl RngCore for JitterRng

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

Fill dest with random data.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Fill dest entirely with random data.

impl CryptoRng for JitterRng