gecko-dev/third_party/rust/rand_jitter

rand_jitter

Non-physical true random number generator based on timing jitter.

This crate depends on rand_core and is part of the Rand project.

This crate aims to support all of Rust's std platforms with a system-provided entropy source. Unlike other Rand crates, this crate does not support no_std (handling this gracefully is a current discussion topic).

Links:

• API documentation (master)
• API documentation (docs.rs)
• Changelog

Features

This crate has optional std support which is disabled by default; this feature is required to provide the JitterRng::new function; without std support a timer must be supplied via JitterRng::new_with_timer.

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;

use std::error::Error;
use std::fs::File;
use std::io::Write;

fn main() -> Result<(), Box<Error>> {
    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)?;
    Ok(())
}

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 noise 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>
   

License

rand_jitter is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT, and COPYRIGHT for details.