Crate lib_q_random 

lib-q-random: Secure Random Number Generation for libQ

This crate provides a comprehensive, secure random number generation system designed specifically for post-quantum cryptography applications in the libQ ecosystem.

Features

• Cryptographically Secure: Uses OS entropy sources; on x86 / x86_64 with std, optional RDRAND is available through the hardware entropy source
• Multiple Providers: Support for OS, deterministic, and hardware entropy sources
• Entropy Validation: Comprehensive entropy quality assessment and validation
• no_std Support: Works in constrained environments without standard library
• WASM Compatible: Full support for WebAssembly and browser environments
• Zero-Copy: Efficient memory usage with minimal allocations
• Thread-Safe: Safe for use in multi-threaded environments
• Extensible: Plugin architecture for custom entropy sources
• Custom Entropy Sources: Secure callback-based system for plugging in custom entropy sources in no_std and WASM environments

Quick Start

With std/alloc features

#[cfg(feature = "alloc")]
{
    use lib_q_random::{
        EntropySource,
        LibQRng,
        RngProvider,
    };
    use rand_core::Rng;

    // Create a secure RNG for production use
    let mut rng = LibQRng::new_secure().unwrap();

    // Generate random bytes
    let mut bytes = [0u8; 32];
    rng.fill_bytes(&mut bytes);

    // Create a deterministic RNG for testing (32-byte KT128 seed)
    let mut test_rng = LibQRng::new_deterministic([1; 32]);
}

Custom Entropy Sources (no_std/WASM)

#[cfg(feature = "custom-entropy")]
{
    use lib_q_random::{
        custom_entropy::{CustomEntropySource, EntropyContext, EntropyQuality, CustomEntropyConfig},
        register_custom_entropy_source, unregister_custom_entropy_source,
        new_secure_rng
    };
    use rand_core::Rng;

    // Define your custom entropy callback
    unsafe extern "C" fn my_entropy_callback(dest: *mut u8, len: usize, _context: *mut u8) -> i32 {
        // Fill dest with len bytes of entropy from your source
        for i in 0..len {
            unsafe {
                *dest.add(i) = (i as u8).wrapping_add(42); // Example entropy source
            }
        }
        0
    }

    // Create and register the custom entropy source
    let context = EntropyContext::empty();
    let config = CustomEntropyConfig::default();
    let source = CustomEntropySource {
        callback: my_entropy_callback,
        context,
        quality: EntropyQuality::Hardware,
        config,
        source_id: "my_hardware_rng",
    };

    // Register the source (must remain valid for the lifetime of usage)
    unsafe {
        register_custom_entropy_source(&source);
    }

    // Now create RNGs that will use your custom entropy source
    let mut rng = new_secure_rng().unwrap();
    let mut bytes = [0u8; 32];
    rng.fill_bytes(&mut bytes);

    // Clean up when done
    unregister_custom_entropy_source();
}

With no_std features

#[cfg(not(feature = "alloc"))]
{
    use lib_q_random::{
        new_deterministic_rng_no_std,
        new_secure_rng_no_std,
    };
    use rand_core::Rng;

    // Create a secure RNG for production use
    let mut rng = new_secure_rng_no_std().unwrap();

    // Generate random bytes
    let mut bytes = [0u8; 32];
    rng.fill_bytes(&mut bytes);

    // Create a deterministic RNG for testing
    let mut test_rng = new_deterministic_rng_no_std([1; 32]);
}

Architecture

The crate is organized into several key components:

• Core Traits: Define the interface for RNG providers and entropy sources
• Providers: Implement different RNG strategies (OS, deterministic, hardware)
• Validation: Entropy quality assessment and security validation
• Factory: RNG creation and configuration management

Security Considerations

• Production randomness comes from OS or registered hardware/custom entropy sources; APIs return an error when secure entropy is unavailable instead of substituting weak RNGs.
• Deterministic constructors (LibQRng::new_deterministic, NoStdRng::new_deterministic, new_deterministic_rng, etc.) use KT128 (KangarooTwelve) XOF expansion keyed by the caller’s 32-byte seed (or SplitMix64-expanded u64 for *_from_u64). They are for tests, KATs, and reproducible benchmarks: treat the seed like a symmetric key; if it is guessable, the entire stream is guessable.
• Entropy validation applies to non-deterministic sources.
• Secure memory clearing and constant-time expectations are documented per algorithm crate.

Re-exports

pub use deterministic_rng::DeterministicRng;

pub use kt128_expander::DOMAIN_HPKE_RNG;

pub use kt128_expander::DOMAIN_LIBQ_DET_RNG;

pub use kt128_expander::KT128_DET_GOLDEN_U64_SEED_64;

pub use kt128_expander::KT128_DET_GOLDEN_ZERO_SEED_64;

pub use kt128_expander::Kt128Expander;

pub use error::Error;

pub use error::Result;

pub use provider::LibQRng;

pub use specialized::Kt128Rng;

pub use traits::RngProvider;

pub use traits::EntropySource;

pub use traits::SecureRng;

pub use traits::SecurityLevel;

pub use validation::EntropyQuality;

pub use validation::EntropyValidator;

Modules

custom_entropy

Custom Entropy Source System for no_std and WASM Environments

deterministic_rng

Lightweight deterministic RNG for STARK/ZKP testing.

entropy

Entropy source implementations

error

Error types for lib-q-random

kt128_expander

KT128 (KangarooTwelve) deterministic byte expansion for test and KAT RNGs.

provider

RNG provider implementations

saturnin_det

Saturnin CTR deterministic byte expansion (optional deterministic-saturnin feature).

specialized

Specialized random number generation implementations for different algorithms

traits

Core traits for lib-q-random

validation

Entropy validation and quality assessment

Constants

DEFAULT_ENTROPY_SIZE

Default entropy buffer size

MAX_ENTROPY_BITS

Maximum entropy bits for validation

MIN_ENTROPY_BITS

Minimum entropy bits required for cryptographic operations

VERSION

Version information

Functions

fill_entropy

Fill dest with cryptographically secure bytes from the OS entropy source.

get_custom_entropy_source_info

Get information about the currently registered entropy source

has_custom_entropy_source

Check if a custom entropy source is currently registered

new_custom_rng

Create a new RNG with custom entropy source

new_deterministic_rng

Create a new deterministic RNG instance

new_deterministic_rng_from_u64

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

new_secure_rng

Create a new secure RNG instance

register_custom_entropy_source^⚠

Register a custom entropy source for the current thread

unregister_custom_entropy_source

Unregister the current custom entropy source