fuchsia / fuchsia / refs/heads/releases/dogfood / . / third_party / rust_crates / vendor / rand_jitter

tree: 969cd031e7cafb9f229b54cc7e17c6b0873c932b [path history] [tgz]

- benches/
- src/
- tests/
- .cargo-checksum.json
- Cargo.toml
- CHANGELOG.md
- COPYRIGHT
- LICENSE-APACHE
- LICENSE-MIT
- README.md

third_party/rust_crates/vendor/rand_jitter/README.md

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:

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`

.

`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.

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

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

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

`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.