Struct RandomGenerator 

pub struct RandomGenerator<G: ByteRandomGenerator>(/* private fields */);

A cryptographically secure random number generator.

This csprng is used by every objects that needs sampling in the library. If the proper instructions are available on the machine, it will use an hardware-accelerated variant for the generation. If not, a fallback software version will be used.

Safe multithreaded use

When using a csprng in a multithreaded setting, it is important to make sure that the same sequence of bytes is not generated twice on two different threads. This csprng offers a simple way to ensure that: any generator can be forked into several bounded generators, which are able to sample a fixed number of bytes. This forking operation has the effect of shifting the state of the parent generator accordingly. This way, the children generators can be used by the different threads safely:

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
assert_eq!(generator.remaining_bytes(), None); // The generator is unbounded.
let children = generator
    .try_fork(5, 2) // 5 generators each able to generate 2 bytes.
    .unwrap()
    .collect::<Vec<_>>();
for child in children.into_iter() {
    assert_eq!(child.remaining_bytes(), Some(2));
    std::thread::spawn(move || {
        let child = child;
        // use the prng to generate 2 bytes.
        // ...
    });
}
// use the parent to generate as many bytes as needed.

Implementations

impl<G: ByteRandomGenerator> RandomGenerator<G>

pub fn generate_next(&mut self) -> u8

pub fn new(params: impl Into<AesCtrParams>) -> Self

Generate a new generator, optionally seeding it with the given value.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

pub fn next_table_index(&self) -> Option<TableIndex>

pub fn remaining_bytes(&self) -> Option<usize>

Return the number of bytes that can still be generated, if the generator is bounded.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
assert_eq!(generator.remaining_bytes(), None);
let generator = generator.try_fork(1, 50).unwrap().next().unwrap();
assert_eq!(generator.remaining_bytes(), Some(50));

pub fn try_fork( &mut self, n_child: usize, bytes_per_child: usize, ) -> Result<impl Iterator<Item = Self>, ForkError>

Tries to fork the current generator into n_child generator bounded to bytes_per_child. If n_child*bytes_per_child exceeds the bound of the current generator, the method returns None.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let children = generator.try_fork(5, 50).unwrap().collect::<Vec<_>>();

pub fn random_from_distribution<Scalar, D>(&mut self, distribution: D) -> Scalar

where D: Distribution, Scalar: RandomGenerable<D>,

Generate a random scalar from the given distribution under the native modulus.

Example

use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let random = generator.random_from_distribution::<u8, _>(Uniform);
let random = generator.random_from_distribution::<i8, _>(Uniform);
let random = generator.random_from_distribution::<u64, _>(Gaussian {
    mean: 0.0,
    std: 1.0,
});

pub fn random_from_distribution_custom_mod<Scalar, D>( &mut self, distribution: D, custom_modulus: CiphertextModulus<Scalar>, ) -> Scalar

where D: Distribution, Scalar: UnsignedInteger + RandomGenerable<D, CustomModulus = Scalar>,

Generate a random unsigned integer from the given distribution under a custom modulus. This is only supported for unsigned integers for now.

Example

use tfhe::core_crypto::commons::ciphertext_modulus::CiphertextModulus;
use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let custom_modulus = CiphertextModulus::new((1 << 64) - (1 << 32) + 1);

let random = generator.random_from_distribution_custom_mod::<u64, _>(Uniform, custom_modulus);
let random = generator.random_from_distribution_custom_mod::<u64, _>(
    Gaussian {
        mean: 0.0,
        std: 1.0,
    },
    custom_modulus,
);

pub fn fill_slice_with_random_from_distribution<Scalar, D>( &mut self, output: &mut [Scalar], distribution: D, )

where D: Distribution, Scalar: RandomGenerable<D>,

Generate a random scalar from the given distribution under the native modulus.

Example

use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let mut random = vec![0u8; 8];
generator.fill_slice_with_random_from_distribution(&mut random, Uniform);
let mut random = vec![0i8; 8];
generator.fill_slice_with_random_from_distribution(&mut random, Uniform);
let mut random = vec![0u64; 8];
generator.fill_slice_with_random_from_distribution(
    &mut random,
    Gaussian {
        mean: 0.0,
        std: 1.0,
    },
);

pub fn fill_slice_with_random_from_distribution_custom_mod<Scalar, D>( &mut self, output: &mut [Scalar], distribution: D, custom_modulus: CiphertextModulus<Scalar>, )

where D: Distribution, Scalar: UnsignedInteger + RandomGenerable<D, CustomModulus = Scalar>,

Generate a random unsigned integer from the given distribution under a custom modulus. This is only supported for unsigned integers for now.

Example

use tfhe::core_crypto::commons::ciphertext_modulus::CiphertextModulus;
use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let custom_modulus = CiphertextModulus::new((1 << 64) - (1 << 32) + 1);

let mut random = vec![0u64; 8];
generator.fill_slice_with_random_from_distribution_custom_mod(
    &mut random,
    Uniform,
    custom_modulus,
);
let mut random = vec![0u64; 8];
generator.fill_slice_with_random_from_distribution_custom_mod(
    &mut random,
    Gaussian {
        mean: 0.0,
        std: 1.0,
    },
    custom_modulus,
);

pub fn unsigned_integer_slice_wrapping_add_random_from_distribution_assign<Scalar, D>( &mut self, output: &mut [Scalar], distribution: D, )

where D: Distribution, Scalar: UnsignedInteger + RandomGenerable<D>,

Add a random scalar from the given distribution under the native modulus.

Example

use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let mut random = vec![0u8; 8];
generator
    .unsigned_integer_slice_wrapping_add_random_from_distribution_assign(&mut random, Uniform);
let mut random = vec![0u64; 8];
generator.unsigned_integer_slice_wrapping_add_random_from_distribution_assign(
    &mut random,
    Gaussian {
        mean: 0.0,
        std: 1.0,
    },
);

pub fn unsigned_integer_slice_wrapping_add_random_from_distribution_custom_mod_assign<Scalar, D>( &mut self, output: &mut [Scalar], distribution: D, custom_modulus: CiphertextModulus<Scalar>, )

where D: Distribution, Scalar: UnsignedInteger + RandomGenerable<D, CustomModulus = Scalar>,

Add a random gaussian value to each element in a slice.

Example

use tfhe::core_crypto::commons::ciphertext_modulus::CiphertextModulus;
use tfhe::core_crypto::commons::math::random::{Gaussian, RandomGenerator, Uniform};
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;

let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let custom_mod_u8 = CiphertextModulus::try_new_power_of_2(7).unwrap();
let mut random = vec![0u8; 8];
generator.unsigned_integer_slice_wrapping_add_random_from_distribution_custom_mod_assign(
    &mut random,
    Uniform,
    custom_mod_u8,
);

let custom_mod_u64 = CiphertextModulus::try_new_power_of_2(63).unwrap();
let mut random = vec![0u64; 8];
generator.unsigned_integer_slice_wrapping_add_random_from_distribution_custom_mod_assign(
    &mut random,
    Gaussian {
        mean: 0.0,
        std: 1.0,
    },
    custom_mod_u64,
);

pub fn random_uniform<Scalar>(&mut self) -> Scalar

where Scalar: RandomGenerable<Uniform>,

Generate a random uniform unsigned integer.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let random = generator.random_uniform::<u8>();
let random = generator.random_uniform::<u16>();
let random = generator.random_uniform::<u32>();
let random = generator.random_uniform::<u64>();
let random = generator.random_uniform::<u128>();

let random = generator.random_uniform::<i8>();
let random = generator.random_uniform::<i16>();
let random = generator.random_uniform::<i32>();
let random = generator.random_uniform::<i64>();
let random = generator.random_uniform::<i128>();

pub fn random_uniform_custom_mod<Scalar>( &mut self, custom_modulus: CiphertextModulus<Scalar>, ) -> Scalar

where Scalar: UnsignedInteger + RandomGenerable<Uniform, CustomModulus = Scalar>,

Generate a random uniform unsigned integer. This is only supported for unsigned integers at the moment.

Example

use tfhe::core_crypto::commons::ciphertext_modulus::CiphertextModulus;
use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));

let random =
    generator.random_uniform_custom_mod::<u8>(CiphertextModulus::try_new(1 << 8).unwrap());
let random =
    generator.random_uniform_custom_mod::<u16>(CiphertextModulus::try_new(1 << 8).unwrap());
let random =
    generator.random_uniform_custom_mod::<u32>(CiphertextModulus::try_new(1 << 8).unwrap());
let random =
    generator.random_uniform_custom_mod::<u64>(CiphertextModulus::try_new(1 << 8).unwrap());
let random =
    generator.random_uniform_custom_mod::<u128>(CiphertextModulus::try_new(1 << 8).unwrap());

pub fn fill_slice_with_random_uniform<Scalar>(&mut self, output: &mut [Scalar])

where Scalar: RandomGenerable<Uniform>,

Fill a slice with random uniform values.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.fill_slice_with_random_uniform(&mut vec);
assert!(vec.iter().any(|&x| x != 0));

pub fn fill_slice_with_random_uniform_custom_mod<Scalar>( &mut self, output: &mut [Scalar], custom_modulus: CiphertextModulus<Scalar>, )

where Scalar: UnsignedInteger + RandomGenerable<Uniform, CustomModulus = Scalar>,

Fill a slice with random uniform values.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe::core_crypto::commons::parameters::CiphertextModulus;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.fill_slice_with_random_uniform_custom_mod(
    &mut vec,
    CiphertextModulus::try_new_power_of_2(31).unwrap(),
);
assert!(vec.iter().any(|&x| x != 0));

pub fn random_uniform_binary<Scalar>(&mut self) -> Scalar

where Scalar: RandomGenerable<UniformBinary>,

Generate a random uniform binary value. This will draw one full byte from the underlying csprng.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let random: u32 = generator.random_uniform_binary();

pub fn fill_slice_with_random_uniform_binary<Scalar>( &mut self, output: &mut [Scalar], )

where Scalar: RandomGenerable<UniformBinary>,

Fill a slice with random uniform binary values. This will draw one full byte from the underlying csprng for every element of the slice.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.fill_slice_with_random_uniform_binary(&mut vec);
assert!(vec.iter().any(|&x| x != 0));

pub fn fill_slice_with_random_uniform_binary_bits<Scalar>( &mut self, output: &mut [Scalar], )

where Scalar: UnsignedInteger,

Fill a slice with random uniform binary values. This will only draw as many bytes needed from the underlying csprng to fill the slice with random bits. If the slice len is n, it will draw ceil(n/8) bytes from the csprng.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.fill_slice_with_random_uniform_binary_bits(&mut vec);
assert!(vec.iter().any(|&x| x != 0));

pub fn random_uniform_ternary<Scalar>(&mut self) -> Scalar

where Scalar: RandomGenerable<UniformTernary>,

Generate a random uniform ternary value. This will draw one full byte from the underlying csprng for every element of the slice.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let random: u32 = generator.random_uniform_ternary();

pub fn random_gaussian<Float, Scalar>( &mut self, mean: Float, std: Float, ) -> (Scalar, Scalar)

where Float: FloatingPoint, (Scalar, Scalar): RandomGenerable<Gaussian<Float>>,

Generate two floating point values drawn from a gaussian distribution with input mean and standard deviation.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
// for f32
let (g1, g2): (f32, f32) = generator.random_gaussian(0_f32, 1_f32);
// check that both samples are in 6 sigmas.
assert!(g1.abs() <= 6.);
assert!(g2.abs() <= 6.);
// for f64
let (g1, g2): (f64, f64) = generator.random_gaussian(0_f64, 1_f64);
// check that both samples are in 6 sigmas.
assert!(g1.abs() <= 6.);
assert!(g2.abs() <= 6.);

pub fn fill_slice_with_random_gaussian<Float, Scalar>( &mut self, output: &mut [Scalar], mean: Float, std: Float, )

where Float: FloatingPoint, (Scalar, Scalar): RandomGenerable<Gaussian<Float>>,

Fill a slice with random gaussian values.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0f32; 1000];
generator.fill_slice_with_random_gaussian(&mut vec, 0., 1.);
assert!(vec.iter().any(|&x| x != 0.));

pub fn fill_slice_with_random_gaussian_custom_mod<Float, Scalar>( &mut self, output: &mut [Scalar], mean: Float, std: Float, custom_modulus: CiphertextModulus<Scalar>, )

where Float: FloatingPoint, Scalar: UnsignedTorus + CastInto<Float>, (Scalar, Scalar): RandomGenerable<Gaussian<Float>, CustomModulus = Scalar>,

Fill a slice with random gaussian values.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe::core_crypto::commons::parameters::CiphertextModulus;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u64; 1000];
generator.fill_slice_with_random_gaussian_custom_mod(
    &mut vec,
    0.,
    1.,
    CiphertextModulus::try_new_power_of_2(63).unwrap(),
);
assert!(vec.iter().any(|&x| x != 0));

pub fn unsigned_torus_slice_wrapping_add_random_gaussian_assign<Float, Scalar>( &mut self, output: &mut [Scalar], mean: Float, std: Float, )

where Scalar: UnsignedTorus, Float: FloatingPoint, (Scalar, Scalar): RandomGenerable<Gaussian<Float>>,

Add a random gaussian value to each element in a slice.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.unsigned_torus_slice_wrapping_add_random_gaussian_assign(&mut vec, 0., 1.);
assert!(vec.iter().any(|&x| x != 0));

pub fn unsigned_torus_slice_wrapping_add_random_gaussian_custom_mod_assign<Float, Scalar>( &mut self, output: &mut [Scalar], mean: Float, std: Float, custom_modulus: CiphertextModulus<Scalar>, )

where Float: FloatingPoint, Scalar: UnsignedTorus + CastInto<Float>, (Scalar, Scalar): RandomGenerable<Gaussian<Float>, CustomModulus = Scalar>,

Add a random gaussian value to each element in a slice.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe::core_crypto::commons::parameters::CiphertextModulus;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let mut vec = vec![0u32; 1000];
generator.unsigned_torus_slice_wrapping_add_random_gaussian_custom_mod_assign(
    &mut vec,
    0.,
    1.,
    CiphertextModulus::try_new_power_of_2(31).unwrap(),
);
assert!(vec.iter().any(|&x| x != 0));

impl<G: ParallelByteRandomGenerator> RandomGenerator<G>

pub fn par_try_fork( &mut self, n_child: usize, bytes_per_child: usize, ) -> Result<impl IndexedParallelIterator<Item = Self>, ForkError>

Tries to fork the current generator into n_child generator bounded to bytes_per_child, as a parallel iterator.

If n_child*bytes_per_child exceeds the bound of the current generator, the method returns None.

Example

use tfhe::core_crypto::commons::math::random::RandomGenerator;
use tfhe_csprng::generators::SoftwareRandomGenerator;
use tfhe_csprng::seeders::Seed;
let mut generator = RandomGenerator::<SoftwareRandomGenerator>::new(Seed(0));
let children = generator.try_fork(5, 50).unwrap().collect::<Vec<_>>();

Trait Implementations

impl<G: ByteRandomGenerator> RngCore for RandomGenerator<G>

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

Fill dest with random data.

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

Fill dest entirely with random data.