vendor/rand_jitter/README.md

   1 # rand_jitter
   2 [![Build Status](https://travis-ci.org/rust-random/rand.svg?branch=master)](https://travis-ci.org/rust-random/rand)
   3 [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-random/rand?svg=true)](https://ci.appveyor.com/project/rust-random/rand)
   4 [![Latest version](https://img.shields.io/crates/v/rand_os.svg)](https://crates.io/crates/rand_jitter)
   5 [![Book](https://img.shields.io/badge/book-master-yellow.svg)](https://rust-random.github.io/book/)
   6 [![API](https://img.shields.io/badge/api-master-yellow.svg)](https://rust-random.github.io/rand/rand_jitter)
   7 [![API](https://docs.rs/rand_os/badge.svg)](https://docs.rs/rand_jitter)
   8 [![Minimum rustc version](https://img.shields.io/badge/rustc-1.22+-lightgray.svg)](https://github.com/rust-random/rand#rust-version-requirements)
   9
  10 Non-physical true random number generator based on timing jitter.
  11
  12 This crate depends on [rand_core](https://crates.io/crates/rand_core) and is
  13 part of the [Rand project](https://github.com/rust-random/rand).
  14
  15 This crate aims to support all of Rust's `std` platforms with a system-provided
  16 entropy source. Unlike other Rand crates, this crate does not support `no_std`
  17 (handling this gracefully is a current discussion topic).
  18
  19 Links:
  20
  21 -   [API documentation (master)](https://rust-random.github.io/rand/rand_jitter)
  22 -   [API documentation (docs.rs)](https://docs.rs/rand_jitter)
  23 -   [Changelog](CHANGELOG.md)
  24
  25 ## Features
  26
  27 This crate has optional `std` support which is *disabled by default*;
  28 this feature is required to provide the `JitterRng::new` function;
  29 without `std` support a timer must be supplied via `JitterRng::new_with_timer`.
  30
  31 ## Quality testing
  32
  33 `JitterRng::new()` has build-in, but limited, quality testing, however
  34 before using `JitterRng` on untested hardware, or after changes that could
  35 effect how the code is optimized (such as a new LLVM version), it is
  36 recommend to run the much more stringent
  37 [NIST SP 800-90B Entropy Estimation Suite](https://github.com/usnistgov/SP800-90B_EntropyAssessment).
  38
  39 Use the following code using `timer_stats` to collect the data:
  40
  41 ```rust
  42 use rand_jitter::JitterRng;
  43
  44 use std::error::Error;
  45 use std::fs::File;
  46 use std::io::Write;
  47
  48 fn main() -> Result<(), Box<Error>> {
  49     let mut rng = JitterRng::new()?;
  50
  51     // 1_000_000 results are required for the
  52     // NIST SP 800-90B Entropy Estimation Suite
  53     const ROUNDS: usize = 1_000_000;
  54     let mut deltas_variable: Vec<u8> = Vec::with_capacity(ROUNDS);
  55     let mut deltas_minimal: Vec<u8> = Vec::with_capacity(ROUNDS);
  56
  57     for _ in 0..ROUNDS {
  58         deltas_variable.push(rng.timer_stats(true) as u8);
  59         deltas_minimal.push(rng.timer_stats(false) as u8);
  60     }
  61
  62     // Write out after the statistics collection loop, to not disturb the
  63     // test results.
  64     File::create("jitter_rng_var.bin")?.write(&deltas_variable)?;
  65     File::create("jitter_rng_min.bin")?.write(&deltas_minimal)?;
  66     Ok(())
  67 }
  68 ```
  69
  70 This will produce two files: `jitter_rng_var.bin` and `jitter_rng_min.bin`.
  71 Run the Entropy Estimation Suite in three configurations, as outlined below.
  72 Every run has two steps. One step to produce an estimation, another to
  73 validate the estimation.
  74
  75 1. Estimate the expected amount of entropy that is at least available with
  76    each round of the entropy collector. This number should be greater than
  77    the amount estimated with `64 / test_timer()`.
  78    ```sh
  79    python noniid_main.py -v jitter_rng_var.bin 8
  80    restart.py -v jitter_rng_var.bin 8 <min-entropy>
  81    ```
  82 2. Estimate the expected amount of entropy that is available in the last 4
  83    bits of the timer delta after running noice sources. Note that a value of
  84    `3.70` is the minimum estimated entropy for true randomness.
  85    ```sh
  86    python noniid_main.py -v -u 4 jitter_rng_var.bin 4
  87    restart.py -v -u 4 jitter_rng_var.bin 4 <min-entropy>
  88    ```
  89 3. Estimate the expected amount of entropy that is available to the entropy
  90    collector if both noise sources only run their minimal number of times.
  91    This measures the absolute worst-case, and gives a lower bound for the
  92    available entropy.
  93    ```sh
  94    python noniid_main.py -v -u 4 jitter_rng_min.bin 4
  95    restart.py -v -u 4 jitter_rng_min.bin 4 <min-entropy>
  96    ```
  97
  98 ## License
  99
 100 `rand_jitter` is distributed under the terms of both the MIT license and the
 101 Apache License (Version 2.0).
 102
 103 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
 104 [COPYRIGHT](COPYRIGHT) for details.