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

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 and hardware RNGs when available
• 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

Add this to your Cargo.toml:

[dependencies]
lib-q-random = "0.0.4"

# For custom entropy sources in no_std/WASM environments
lib-q-random = { version = "0.0.4", features = ["custom-entropy"] }

Basic Usage

use lib_q_random::{LibQRng, new_secure_rng, new_deterministic_rng};

// Create a secure RNG for production use
let mut rng = new_secure_rng()?;

// 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([1; 32]);
test_rng.fill_bytes(&mut bytes);

Advanced Usage

use lib_q_random::{
    LibQRng, EntropyValidator, EntropyQuality,
    entropy::{EntropySourceFactory, UserEntropySource},
    traits::{RngConfig, SecurityLevel}
};

// Create a custom RNG with user-provided entropy
let entropy_data = vec![1, 2, 3, 4, 5, 6, 7, 8];
let entropy_source = UserEntropySource::new(entropy_data);

Custom Entropy Sources (no_std/WASM)

For no_std and WASM environments, you can plug in custom entropy sources:

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

    // 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
        // Return 0 on success, non-zero on failure
        for i in 0..len {
            unsafe {
                *dest.add(i) = get_entropy_from_hardware(i); // Your 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, // or Os, User, Deterministic
        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_no_std().unwrap();
    let mut bytes = [0u8; 32];
    rng.fill_bytes(&mut bytes);

    // Clean up when done
    unregister_custom_entropy_source();
}

Feature Flags

• std: Enable standard library features (default)
• no_std: Enable no_std compatibility
• custom-entropy: Enable custom entropy source support
• secure: Enable cryptographically secure RNGs
• deterministic: Enable deterministic RNGs for testing
• entropy-validation: Enable entropy quality validation
• zeroize: Enable automatic memory zeroization
• wasm: Enable WebAssembly support

Security Considerations

• Entropy Quality: Always use high-quality entropy sources for cryptographic operations
• Custom Entropy: When using custom entropy sources, ensure they provide cryptographically secure randomness
• Memory Safety: Sensitive data is automatically zeroized when using the zeroize feature
• Thread Safety: All RNG implementations are thread-safe and can be used in multi-threaded environments

Architecture

The crate is organized into several key components:

Core Traits

• SecureRng: Enhanced random number generator trait for cryptographic applications
• EntropySource: Trait for entropy sources that provide random data
• RngProvider: Trait for RNG providers that create and manage RNG instances

Providers

• LibQRng: Main RNG implementation with unified interface
• OsEntropySource: Operating system entropy source
• HardwareEntropySource: RDRAND on x86 / x86_64 when the std feature is enabled and the CPU supports it; otherwise unavailable (use OsEntropySource on other targets)
• DeterministicEntropySource: Deterministic source for testing
• UserEntropySource: User-provided entropy source

Validation

• EntropyValidator: Comprehensive entropy validation and quality assessment
• EntropyQuality: Entropy quality assessment result
• quick_entropy_check: Quick entropy validation for small samples

Security Considerations

• All RNGs are cryptographically secure by default
• Entropy validation ensures sufficient randomness
• Secure memory clearing prevents key material leakage
• Constant-time operations prevent timing attacks
• Comprehensive error handling prevents fallback to weak randomness

Platform Support

Operating Systems

• Linux (using /dev/urandom)
• macOS (using SecRandomCopyBytes)
• Windows (using CryptGenRandom)
• FreeBSD, OpenBSD, NetBSD
• WebAssembly (using crypto.getRandomValues())

Hardware RNGs

• Intel RDRAND (when available)
• ARM TRNG (when available)
• Platform-specific hardware RNGs

Feature Flags

• std: Standard library support (default)
• alloc: Dynamic memory allocation support
• secure: Cryptographically secure RNGs (default)
• deterministic: Deterministic RNGs for testing (KT128 expansion; always available with lib-q-k12)
• hash: HPKE Kt128Rng export
• hpke: HPKE RNG integration (hash)
• deterministic-saturnin: Optional Saturnin CTR deterministic RNG (LibQRng::new_deterministic_saturnin)
• hardware: Hardware RNG support
• zeroize: Secure memory clearing (default)
• entropy-validation: Entropy validation features
• wasm: WebAssembly support
• js: JavaScript bindings

Examples

Basic Random Generation

use lib_q_random::new_secure_rng;

let mut rng = new_secure_rng()?;
let mut key = [0u8; 32];
rng.fill_bytes(&mut key);

Deterministic Testing

use lib_q_random::new_deterministic_rng;

let mut seed = [0u8; 32];
seed[..8].copy_from_slice(&[1, 2, 3, 4, 5, 6, 7, 8]);
let mut rng = new_deterministic_rng(seed);
let mut bytes = [0u8; 16];
rng.fill_bytes(&mut bytes);
// bytes will be the same every time with the same seed (KT128 / libQ-DET-RNG-v1)

Migration (0.0.3 → 0.0.4)

Deterministic APIs are unchanged by name, but output bytes differ: ChaCha20 was replaced with KT128 (KangarooTwelve) and domain-separated expansion. new_deterministic_from_u64 now uses SplitMix64 to form a 32-byte seed. Re-record any test vectors that pinned ChaCha20 output. See CHANGELOG.md.

Custom Entropy Source

use lib_q_random::{LibQRng, entropy::UserEntropySource};

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);

Entropy Validation

use lib_q_random::{EntropyValidator, validation::quick_entropy_check};

let validator = EntropyValidator::new();
let data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16];

// Quick check
if quick_entropy_check(&data) {
    println!("Data appears to have good entropy");
}

// Full validation
match validator.validate_entropy(&data) {
    Ok(quality) => println!("Entropy quality: {}", quality),
    Err(e) => println!("Entropy validation failed: {}", e),
}

Performance

The crate is designed for high performance with minimal overhead:

• Zero-copy operations where possible
• Efficient entropy source selection
• Optimized validation algorithms
• Minimal memory allocations

Benchmarks are available in the benches/ directory.

Testing

The crate includes comprehensive tests:

• Unit tests for all components
• Integration tests for end-to-end functionality
• Property-based tests for statistical properties
• Performance benchmarks

Run tests with:

cargo test
cargo test --features "test-vectors"

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Security

For security-related issues, please see our Security Policy.

Changelog

See CHANGELOG.md for a list of changes.

Related Projects

• libQ - Post-quantum cryptography library
• lib-q-core - Core types and traits
• lib-q-kem - Key encapsulation mechanisms