[][src]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.

Methods

impl JitterRng
[src]

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

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
[src]

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.next_u64();

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

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

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>
[src]

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
[src]

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 this crate's README on how to use timer_stats to test the quality of JitterRng.

Trait Implementations

impl Clone for JitterRng
[src]

fn clone_from(&mut self, source: &Self)
1.0.0
[src]

Performs copy-assignment from source. Read more

impl Debug for JitterRng
[src]

impl RngCore for JitterRng
[src]

impl CryptoRng for JitterRng
[src]

Auto Trait Implementations

impl Send for JitterRng

impl Sync for JitterRng

Blanket Implementations

impl<R> Rng for R where
    R: RngCore + ?Sized
[src]

fn gen<T>(&mut self) -> T where
    Standard: Distribution<T>, 
[src]

Return a random value supporting the [Standard] distribution. Read more

fn gen_range<T: SampleUniform, B1, B2>(&mut self, low: B1, high: B2) -> T where
    B1: SampleBorrow<T> + Sized,
    B2: SampleBorrow<T> + Sized
[src]

Generate a random value in the range [low, high), i.e. inclusive of low and exclusive of high. Read more

fn sample<T, D: Distribution<T>>(&mut self, distr: D) -> T
[src]

Sample a new value, using the given distribution. Read more

Important traits for DistIter<'a, D, R, T>
fn sample_iter<'a, T, D: Distribution<T>>(
    &'a mut self,
    distr: &'a D
) -> DistIter<'a, D, Self, T> where
    Self: Sized
[src]

Create an iterator that generates values using the given distribution. Read more

fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T)
[src]

Fill dest entirely with random bytes (uniform value distribution), where dest is any type supporting AsByteSliceMut, namely slices and arrays over primitive integer types (i8, i16, u32, etc.). Read more

fn try_fill<T: AsByteSliceMut + ?Sized>(
    &mut self,
    dest: &mut T
) -> Result<(), Error>
[src]

Fill dest entirely with random bytes (uniform value distribution), where dest is any type supporting AsByteSliceMut, namely slices and arrays over primitive integer types (i8, i16, u32, etc.). Read more

fn gen_bool(&mut self, p: f64) -> bool
[src]

Return a bool with a probability p of being true. Read more

fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool
[src]

Return a bool with a probability of numerator/denominator of being true. I.e. gen_ratio(2, 3) has chance of 2 in 3, or about 67%, of returning true. If numerator == denominator, then the returned value is guaranteed to be true. If numerator == 0, then the returned value is guaranteed to be false. Read more

fn choose<'a, T>(&mut self, values: &'a [T]) -> Option<&'a T>
[src]

Deprecated since 0.6.0:

use SliceRandom::choose instead

Return a random element from values. Read more

fn choose_mut<'a, T>(&mut self, values: &'a mut [T]) -> Option<&'a mut T>
[src]

Deprecated since 0.6.0:

use SliceRandom::choose_mut instead

Return a mutable pointer to a random element from values. Read more

fn shuffle<T>(&mut self, values: &mut [T])
[src]

Deprecated since 0.6.0:

use SliceRandom::shuffle instead

Shuffle a mutable slice in place. Read more

impl<T> From for T
[src]

impl<T, U> Into for T where
    U: From<T>, 
[src]

impl<T> ToOwned for T where
    T: Clone
[src]

type Owned = T

impl<T, U> TryFrom for T where
    T: From<U>, 
[src]

type Error = !

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> Borrow for T where
    T: ?Sized
[src]

impl<T> BorrowMut for T where
    T: ?Sized
[src]

impl<T, U> TryInto for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

🔬 This is a nightly-only experimental API. (try_from)

The type returned in the event of a conversion error.

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> FromCast for T
[src]

impl<T, U> Cast for T where
    U: FromCast<T>, 
[src]

impl<T> FromBits for T
[src]

impl<T, U> IntoBits for T where
    U: FromBits<T>, 
[src]