Crate vitaminc_random 

Vitamin C Random

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

This crate is part of the Vitamin C framework to make cryptography code healthy.

Generatable

Types implementing the Generatable trait can be generated randomly using SafeRand.

use vitaminc_random::{Generatable, SafeRand, SeedableRng};

let mut rng = SafeRand::from_entropy().expect("Failed to seed RNG");
let x: [u8; 32] = Generatable::random(&mut rng).unwrap();

You can implement Generatable for your own types using the derive macro:

use vitaminc_random::{Generatable, SafeRand, SeedableRng};

#[derive(Generatable)]
struct MyStruct {
    id: u32,
    key: [u8; 16],
}

// Create a random number generator and generate an instance of MyStruct.
let mut rng = vitaminc_random::SafeRand::from_entropy().expect("Failed to seed RNG");
let instance: MyStruct = Generatable::random(&mut rng).unwrap();
println!("Generated id: {}", instance.id);

Bounded Random Numbers

SafeRand::next_below(n) returns a value in 0..n, the bound every index-shaped use wants. It makes exactly one 64-bit draw per call, reduced with Lemire’s multiply-high method, so the number of draws does not depend on the values drawn. The reduction’s statistical distance from uniform is at most n / 2⁶⁴; a protocol that needs exact uniformity must account for that term.

use vitaminc_random::{SafeRand, SeedableRng};

let mut rng = SafeRand::from_entropy().expect("Failed to seed RNG");
let index = rng.next_below(10);
assert!(index < 10);

The bound may also be a Protected<u32>, in which case the result is Protected too:

use vitaminc_protected::{Controlled, Protected};
use vitaminc_random::{SafeRand, SeedableRng};

let mut rng = SafeRand::from_entropy().expect("Failed to seed RNG");
let index: Protected<u32> = rng.next_below(Protected::new(10));
assert!(index.risky_unwrap() < 10);

A Protected<u32> bound of zero panics, and that panic is observable on the secret. When a secret bound might be zero, check it once at construction and pass a Protected<NonZeroU32>; that form never panics:

use std::num::NonZeroU32;
use vitaminc_protected::{Controlled, Protected};
use vitaminc_random::{SafeRand, SeedableRng};

let mut rng = SafeRand::from_entropy().expect("Failed to seed RNG");
let bound = Protected::new(NonZeroU32::new(10).expect("non-zero"));
let index: Protected<u32> = rng.next_below(bound);
assert!(index.risky_unwrap() < 10);

All three are the BoundedRng::next_below trait method. The older inclusive form, next_bounded(max) for 0..=max, lives on the separate, deprecated BoundedRngInclusive trait and on SafeRand::next_bounded_u32; both are deprecated in favour of next_below(max + 1).

CipherStash

Vitamin C is brought to you by the team at CipherStash.

License: MIT

Structs

SafeRand

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

Enums

RandomError

Traits

BoundedRng

Bounded draws over one fixed-count Lemire reduction.

BoundedRngInclusiveDeprecated

The older inclusive bounded draw, 0..=max.

Fill

Support filling a slice with random data

Generatable

A trait for types that can be generated randomly. The random number generator is passed as an argument to the generate method and must implement the SafeRand trait.

Rng

Trait for infallible random number generators

SeedableRng

A random number generator that can be explicitly seeded.

Derive Macros

Generatable

Derive macro for Generatable