Struct LibQRng 

pub struct LibQRng { /* private fields */ }

Main libQ random number generator

This is the primary RNG implementation for the libQ ecosystem, providing a unified interface for secure random number generation across different platforms and use cases.

Implementations

impl LibQRng

pub fn new_secure() -> Result<Self>

Create a new secure RNG using the best available entropy source

This method creates a cryptographically secure RNG using the highest quality entropy source available on the current platform.

Errors

Returns an error if no secure entropy source is available.

Examples

use lib_q_random::LibQRng;
use rand_core::Rng;

let mut rng = LibQRng::new_secure().unwrap();
let mut bytes = [0u8; 32];
rng.fill_bytes(&mut bytes);

pub fn new_deterministic(seed: [u8; 32]) -> Self

Create a new deterministic RNG for testing

Initializes a KT128 (KangarooTwelve) XOF byte stream from a 256-bit seed. Suitable for KATs and regression tests. Unpredictability is only as strong as the seed: this is not a substitute for Self::new_secure in production.

Arguments

• seed - 32-byte seed; must be chosen explicitly for tests

Examples

use lib_q_random::LibQRng;
use rand_core::Rng;

let mut rng = LibQRng::new_deterministic([1; 32]);
let mut bytes = [0u8; 32];
rng.fill_bytes(&mut bytes);

pub fn new_deterministic_from_u64(seed: u64) -> Self

Create a deterministic RNG from a u64 test seed (SplitMix64 → KT128).

pub fn new_deterministic_saturnin(seed: [u8; 32]) -> Result<Self>

Create a deterministic RNG using Saturnin CTR keystream (deterministic-saturnin feature).

Requires alloc. Uses domain crate::kt128_expander::DOMAIN_LIBQ_DET_SATURNIN for the CTR nonce.

Errors

Returns an error if Saturnin keystream generation fails.

pub fn new_custom<T: EntropySource + 'static>(entropy_source: T) -> Self

Create a new RNG with a custom entropy source

This method allows creating an RNG with a custom entropy source, useful for specialized applications or testing.

Arguments

• entropy_source - Custom entropy source implementation

Examples

use lib_q_random::LibQRng;
use lib_q_random::entropy::UserEntropySource;
use rand_core::Rng;

let entropy_data = vec![1, 2, 3, 4, 5, 6, 7, 8];
let entropy_source = UserEntropySource::new(entropy_data);
let mut rng = LibQRng::new_custom(entropy_source);

pub fn with_config(config: &RngConfig) -> Result<Self>

Create a new RNG with custom configuration

This method allows creating an RNG with specific configuration parameters for specialized use cases.

Arguments

• config - RNG configuration parameters

Errors

Returns an error if the configuration is invalid or if the RNG cannot be created with the specified parameters.

pub fn is_deterministic(&self) -> bool

Check if this RNG is deterministic

pub fn security_level(&self) -> SecurityLevel

Get the security level of this RNG

pub fn entropy_source_name(&self) -> &'static str

Get the entropy source name

pub fn entropy_source_type(&self) -> EntropySourceType

Get the entropy source type

pub fn reseed_counter(&self) -> u32

Get the reseed counter

pub fn bytes_generated(&self) -> usize

Get the bytes generated since last reseed

pub fn is_secure(&self) -> bool

Check if this RNG is cryptographically secure

pub fn entropy_quality(&self) -> f64

Get the entropy quality estimate (0.0 to 1.0)

impl LibQRng

pub fn fill<T>(&mut self, dest: &mut [T])

where T: Copy + Default,

Fill a slice with random values of any integer type

This method provides a convenient way to fill slices of different integer types with random values, handling the byte conversion internally.

Examples

use lib_q_random::LibQRng;

let mut rng = LibQRng::new_secure().unwrap();
let mut u16_array = [0u16; 10];
rng.fill(&mut u16_array);

Trait Implementations

impl Display for LibQRng

Available on crate feature alloc only.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SecureRng for LibQRng

Available on crate feature alloc only.

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

Fill the buffer with cryptographically secure random bytes

fn next_u32_secure(&mut self) -> Result<u32>

Generate a random u32 with security validation

fn next_u64_secure(&mut self) -> Result<u64>

Generate a random u64 with security validation

fn initialize(&mut self, entropy: &[u8]) -> Result<()>

Initialize the RNG with entropy (if supported)

fn is_secure(&self) -> bool

Check if the RNG is cryptographically secure

fn entropy_quality(&self) -> f64

Get the entropy quality estimate (0.0 to 1.0)

fn security_level(&self) -> SecurityLevel

Get the RNG’s security level

fn reseed(&mut self) -> Result<()>

Reseed the RNG with fresh entropy

fn state_size(&self) -> usize

Get the RNG’s internal state size

fn reseed_interval(&self) -> Option<usize>

Get the RNG’s reseed interval

impl TryRng for LibQRng

Available on crate feature alloc only.

type Error = Infallible

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, dest: &mut [u8]) -> Result<(), Self::Error>

Fill dst entirely with random data.

impl TryCryptoRng for LibQRng

Available on crate feature alloc only.