Struct SafeRand 

pub struct SafeRand(/* private fields */);

A secure random number generator that is safe to use for cryptographic purposes.

Wipes its key schedule and buffered keystream on drop.

Implementations

impl SafeRand

pub fn next_below<T>(&mut self, n: T) -> <Self as BoundedRng<T>>::Output

where Self: BoundedRng<T>,

A value in 0..n: at least 0, strictly below n, uniform to within the bias bound stated below. This is the bound every index-shaped use wants (n items, pick one) and the one std and rand ranges use.

Exactly one 64-bit draw per call, reduced with Lemire’s multiply-high method: no rejection loop and no branch on the value drawn, so the number of draws does not depend on the values drawn. That matters when the generator is seeded from secret material, as in permutation-key derivation, where a rejection loop’s retry count would leak through timing.

The reduction’s statistical distance from uniform is at most n / 2⁶⁴: below 2⁻⁵⁵ for n ≤ 256 and still at most 2⁻³² at n = u32::MAX. A protocol that needs exact uniformity must account for that term.

The bound may be a plain u32, a Protected<u32>, or a Protected<NonZeroU32>; the last is the form for a secret bound that might be zero, since it moves the zero check to construction and makes the draw itself total. All three are the BoundedRng::next_below trait method, reachable here without importing the trait.

Panics

Panics if n == 0: the range 0..0 is empty and has no value to return. Callers that compute n should check it first. When n is a Protected<u32> the panic is observable on a secret, so a caller whose secret bound may be zero should pass a Protected<NonZeroU32> instead, which never panics.

pub fn next_bounded_u32(&mut self, max: u32) -> u32

👎Deprecated:

inclusive 0..=max; use next_below(max + 1), or next_below(n) when you have a length n

A value in 0..=max, for every max up to and including u32::MAX, with the same fixed-count draw and the same (max + 1) / 2⁶⁴ bias bound as next_below. This is the BoundedRngInclusive::next_bounded trait method at u32.

Deprecated: earlier versions honoured the inclusive bound only when max was not a power of two and were exclusive otherwise, so callers written against either meaning were wrong for some inputs (cipherstash/vitaminc#198). The equivalent call is next_below(max + 1) (for max == u32::MAX that is the whole word: use Rng::next_u32), or next_below(n) when the caller has a length n rather than a maximum.

Besides the power-of-two case, both the value drawn for a given seed and the number of words taken from the stream changed; see BoundedRngInclusive for what that means for existing callers.

pub fn from_entropy() -> Result<Self, RandomError>

Creates a new SafeRand seeded from the OS random number generator.

pub fn from_controlled_seed<C>(seed: C) -> Self

where C: Controlled<Inner = [u8; 32]>,

A safer alternative to from_seed: the seed is wiped once the generator is built, on every exit from this function.

The unwrapped bytes live in a Zeroizing wrapper from the moment they leave seed’s custody, so the wipe is done by drop glue rather than by a trailing statement. An unwind between unwrapping and returning (e.g. a panic in the generator’s constructor) still wipes them.

Trait Implementations

impl BoundedRng<Protected<NonZero<u32>>> for SafeRand

fn next_below(&mut self, n: Protected<NonZeroU32>) -> Protected<u32>

See BoundedRng::next_below. The bound carries its own non-zero proof, so every input takes the same path here: nothing checks the secret, and the non-zero assertion in the shared reduction cannot fire for a bound of this type.

type Output = Protected<u32>

The type of the value drawn. This is the bound’s own type for u32 and Protected<u32>, and Protected<u32> for a Protected<NonZeroU32> bound, since 0 is a valid draw.

impl BoundedRng<Protected<u32>> for SafeRand

fn next_below(&mut self, n: Protected<u32>) -> Protected<u32>

See BoundedRng::next_below.

Panics

Panics if the wrapped bound is zero. That panic is observable on a secret; a caller whose secret bound may be zero should construct a Protected<NonZeroU32> and use that impl, which never panics.

type Output = Protected<u32>

The type of the value drawn. This is the bound’s own type for u32 and Protected<u32>, and Protected<u32> for a Protected<NonZeroU32> bound, since 0 is a valid draw.

impl BoundedRng<u32> for SafeRand

type Output = u32

The type of the value drawn. This is the bound’s own type for u32 and Protected<u32>, and Protected<u32> for a Protected<NonZeroU32> bound, since 0 is a valid draw.

fn next_below(&mut self, n: u32) -> u32

A value in 0..n: at least 0, strictly below n, uniform to within the n / 2⁶⁴ bias bound documented on BoundedRng.

impl BoundedRngInclusive<Protected<u32>> for SafeRand

fn next_bounded(&mut self, max: Protected<u32>) -> Protected<u32>

👎Deprecated:

inclusive 0..=max; use BoundedRng::next_below(max + 1), or next_below(n) when you have a length n

A value in 0..=max, uniform to within the (max + 1) / 2⁶⁴ bias bound documented on BoundedRng.

impl BoundedRngInclusive<u32> for SafeRand

fn next_bounded(&mut self, max: u32) -> u32

👎Deprecated:

inclusive 0..=max; use BoundedRng::next_below(max + 1), or next_below(n) when you have a length n

A value in 0..=max, uniform to within the (max + 1) / 2⁶⁴ bias bound documented on BoundedRng.

impl SeedableRng for SafeRand

type Seed = [u8; 32]

Seed type, which is restricted to types mutably-dereferenceable as u8 arrays (we recommend [u8; N] for some N).

fn from_seed(seed: Self::Seed) -> Self

Create a new PRNG using the given seed.

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed.

fn from_rng<R>(rng: &mut R) -> Self

where R: Rng + ?Sized,

Create a new PRNG seeded from an infallible Rng.

fn try_from_rng<R>(rng: &mut R) -> Result<Self, <R as TryRng>::Error>

where R: TryRng + ?Sized,

Create a new PRNG seeded from a potentially fallible Rng.

fn fork(&mut self) -> Self

where Self: Rng,

Fork this PRNG

fn try_fork(&mut self) -> Result<Self, Self::Error>

where Self: TryRng,

Fork this PRNG

impl TryCryptoRng for SafeRand

impl TryRng for SafeRand

type Error = !

The type returned in the event of a RNG error.

fn try_next_u32(&mut self) -> Result<u32, Self::Error>

Return the next random u32.

fn try_next_u64(&mut self) -> Result<u64, Self::Error>

Return the next random u64.

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

Fill dst entirely with random data.

impl ZeroizeOnDrop for SafeRand