Product OS Random

A comprehensive random number generation library providing cryptographically secure RNGs, random text/number generators, and word/name generators. Supports no_std environments.

Features

Multiple RNG Backends: Support for StdRng, ThreadRng, OsRng, and custom RNGs
Cryptographic Security: Dedicated CryptoRNG type for security-sensitive operations
no_std Support: Works in embedded and constrained environments
Rich Generators: Random strings, passwords, keys, usernames, emails, and names
Large Datasets: Built-in word lists, names, nouns, and adjectives
Flexible API: Both stateful generators and one-time generation functions

Quick Start

Add to your Cargo.toml:

[dependencies]
product-os-random = "0.0.27"

Basic Usage (Convenience Functions)

The simplest way to generate random data -- just call the top-level functions:

// Generate a random password
let password = product_os_random::random_password(16);

// Generate random alphanumeric string
let code = product_os_random::random_alphanumeric(10);

// Generate a random number in a range
let port = product_os_random::random_usize(1025, 65535);

// Generate random bytes
let bytes = product_os_random::random_bytes(32);

// Generate a cryptographic key
let key = product_os_random::generate_random_key(32);

// Generate a random string from a custom character set
let hex = product_os_random::random_from_characters(16, "0123456789abcdef");

Stateful Generator

For repeated generation, create a RandomGenerator instance:

use product_os_random::{RandomGenerator, RandomGeneratorTemplate};

// Create a generator (uses default RNG)
let mut gen = RandomGenerator::new(None);

// Generate multiple random values efficiently
let bytes = gen.get_random_bytes(32);
let number = gen.get_random_usize(1, 100);
let text = gen.get_random_string(20);

Custom RNG (Power Users)

For reproducible results or specific RNG backends, use the explicit API:

use product_os_random::{RandomGenerator, RandomGeneratorTemplate, RNG};
use rand::SeedableRng;

// Seeded RNG for reproducible output
let rng = RNG::Std(rand::rngs::StdRng::seed_from_u64(42));
let mut gen = RandomGenerator::new(Some(rng));
let number = gen.get_random_usize(1, 100);

// Or use the one-time functions with an explicit RNG
let mut rng = Some(rand::rngs::StdRng::seed_from_u64(42));
let key = RandomGenerator::generate_key_one_time(32, &mut rng);

Cryptographic RNG

use product_os_random::{CryptoRNG, RngCore};

// Use OS randomness for maximum security
let mut rng = CryptoRNG::OS(rand::rngs::OsRng);

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

Feature Flags

Core Features

default - Basic random generation with StdRng and getrandom support
core - Full standard library support with StdRng, ThreadRng, and OsRng
send_only - Send-safe RNG variants only
constrained - Minimal allocation-only mode (requires user-provided RNG)
custom - Custom RNG support with spin locks for no_std
custom_send_only - Custom Send-safe RNG support

Dataset Features

words - Random word generation
nouns - Random noun generation
adjectives - Random adjective generation
names - Random full name generation
first_names - Random first name generation (requires inflections)
last_names - Random last name generation (requires inflections)

Example with Features

[dependencies]
product-os-random = { version = "0.0.27", features = ["core", "names", "first_names", "last_names"] }

use product_os_random::RandomGenerator;

// Generate random username
let username = RandomGenerator::get_simple_random_username_one_time(
    Some(2),
    Some(4),
    Some("_".to_string())
);

// Generate random email
let email = RandomGenerator::get_simple_random_email_one_time(
    Some(2),
    Some(3),
    None,
    vec!["example.com".to_string()]
);

// Generate random first and last names
let first_name = RandomGenerator::get_simple_random_first_name_one_time();
let last_name = RandomGenerator::get_simple_random_last_name_one_time();

Security Considerations

Cryptographic vs Non-Cryptographic RNGs

CryptoRNG: Use for passwords, keys, tokens, and any security-sensitive data
RNG: Suitable for general-purpose randomness (simulations, games, testing)

Thread Safety

RNG::Thread uses thread-local storage
Custom RNG wrappers use Arc<Mutex<>> for safe concurrent access
All RNG types implement Clone for easy distribution

Performance

String generation pre-allocates with String::with_capacity()
Helper functions optimize character filtering
Lock-based custom RNGs may have contention under high concurrency
Dataset features add to binary size (~400K lines of data)

no_std Support

This crate supports no_std environments:

[dependencies]
product-os-random = { version = "0.0.27", default-features = false, features = ["constrained"] }

Note: In constrained mode, you must provide an RNG to all generation functions.

Minimum Supported Rust Version (MSRV)

This crate requires Rust 1.69 or later.

License

This project is licensed under the GPL-3.0-only license.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

Documentation

For detailed API documentation, visit docs.rs/product-os-random.

product-os-random 0.0.30