# oxicrypto-rand TODO

## Status
Minimal CSPRNG (77 SLOC). Provides `OxiRng` — a ChaCha20-based CSPRNG seeded from the OS via `getrandom`. Implements `Rng` trait from `oxicrypto-core`. No fork safety, no thread-local RNG, no random integer generation, no distributions.

## Core Implementation
- [x] Add fork-safe RNG: detect `fork()` via PID tracking and automatically reseed after fork to prevent parent/child sharing CSPRNG state (~60 SLOC) (planned 2026-05-25)
  - **Goal:** OxiRng detects fork() by tracking the process PID and auto-reseeds when PID changes, preventing parent/child CSPRNG state sharing
  - **Design:** Add `last_pid: u32` field to OxiRng struct. In the `fill()` / `try_fill_bytes()` method: at the start, check `std::process::id() != self.last_pid`. If changed, call `reseed()` to get fresh entropy and update `self.last_pid`. This is `#[cfg(unix)]` behavior — on non-Unix platforms, last_pid is always 0 and no check is done. The reseed() function already exists.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Prerequisites:** None — reseed() and OxiRng struct already exist
  - **Tests:** Simulate PID change by temporarily setting last_pid to a different value; verify that subsequent fill() reseeds the RNG (verify by checking that the fill output changes); verify normal operation (same PID) doesn't reseed unnecessarily
  - **Risk:** Moderate — PID tracking adds overhead on every fill(); PID reuse across processes is theoretically possible but not a practical concern; use #[cfg(unix)] guard
- [x] Add thread-local RNG: `thread_rng() -> &mut OxiRng` using `thread_local!` storage, auto-seeded per thread (~40 SLOC) (planned 2026-05-25)
  - **Goal:** thread_rng() function returning a per-thread OxiRng instance for convenient use without explicit RNG management
  - **Design:** `thread_local! { static THREAD_RNG: RefCell<OxiRng> = RefCell::new(OxiRng::new().unwrap_or_else(|_| panic!("Failed to init thread RNG"))); }`. Expose `pub fn with_thread_rng<F, R>(f: F) -> Result<R, CryptoError> where F: FnOnce(&mut OxiRng) -> R` — uses RefCell::try_borrow_mut to avoid panic on re-entrancy. Gated behind `std` feature.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Prerequisites:** None
  - **Tests:** Call with_thread_rng from multiple threads; verify each thread gets different output sequences (via std::thread::spawn); verify single-thread usage works
  - **Risk:** RefCell cannot be used across threads without Mutex; use thread_local! which is inherently per-thread
- [x] `ReseedingRng` wrapper (done 2026-05-25)
  - **Goal:** wraps `OxiRng`, reseeds from OS entropy every N generated bytes (SP 800-90A §9.2 reseed interval).
  - **Design:** struct tracking bytes-since-reseed; on threshold call the existing reseed path. Configurable interval with a safe default (1 MiB). Exposes `bytes_generated()` and `reseed_threshold()` accessors.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** crossing the threshold triggers reseed (observe internal counter reset); output remains CSPRNG-quality.
  - **Risk:** Low.
- [x] Add secure random integer generation: `random_u32() -> u32`, `random_u64() -> u64`, `random_u128() -> u128` with uniform distribution (~30 SLOC) (planned 2026-05-25)
  - **Goal:** random_u32(), random_u64(), random_u128() convenience functions with uniform distribution
  - **Design:** `pub fn random_u32() -> Result<u32, CryptoError>` — creates OxiRng, fills 4 bytes, returns u32::from_le_bytes; `pub fn random_u64() -> Result<u64, CryptoError>` — creates OxiRng, fills 8 bytes, returns u64::from_le_bytes; `pub fn random_u128() -> Result<u128, CryptoError>` — creates OxiRng, fills 16 bytes, returns u128::from_le_bytes; Alternative: use TryRngCore::try_next_u32()/try_next_u64() if available. Also add methods on OxiRng itself: `fn next_u32(&mut self) -> Result<u32, CryptoError>` etc.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Prerequisites:** None
  - **Tests:** Call each function 1000 times; verify non-degenerate output (not all same value); verify return types are correct
  - **Risk:** Very low
- [x] `random_range(min, max)` rejection sampling (done 2026-05-25)
  - **Goal:** uniform `u64` in `[min, max)` without modulo bias.
  - **Design:** rejection sampling over the existing byte source. Error/empty-range handling for `min >= max`. Old single-arg form renamed to `random_range_to(max)`. New public helpers: `random_range_unbiased(rng, min, max)`.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** all samples in range; `min>=max` errors; distribution sanity (no obvious bias over many draws).
  - **Risk:** Low.
- [x] `random_bool(probability)` (done 2026-05-25)
  - **Goal:** biased coin with `p ∈ [0.0, 1.0]`.
  - **Design:** scale p to u64 threshold; compare a fresh random u64. Return error for p outside [0,1]. Both `random_bool(p)` and `random_bool_with_rng(rng, p)` provided.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** p=0.0 always false, p=1.0 always true; ~p frequency over many draws.
  - **Risk:** Low.
- [x] Add `random_bytes(len) -> Vec<u8>` convenience function that allocates and fills a new buffer (~15 SLOC)
- [x] `weighted_choice(weights)` (done 2026-05-25)
  - **Goal:** index sampled proportional to `weights: &[u64]`.
  - **Design:** cumulative sum + `random_range_unbiased(rng, 0, total)`; error on empty/all-zero weights. Both `weighted_choice(weights)` and `weighted_choice_with_rng(rng, weights)` provided.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** zero-weight entries never chosen; rough proportionality; empty errors.
  - **Risk:** Low.
- [x] Add Fisher-Yates shuffle: `shuffle<T>(slice: &mut [T], rng: &mut OxiRng)` for cryptographic shuffling (~20 SLOC) (planned 2026-05-25)
  - **Goal:** shuffle<T>(slice: &mut [T], rng: &mut OxiRng) -> Result<(), CryptoError> for cryptographic shuffling
  - **Design:** Standard Knuth shuffle: `for i in (1..slice.len()).rev() { let j = random_range_with_rng(rng, i + 1)?; slice.swap(i, j); }`. Use an internal helper that takes &mut OxiRng instead of creating a new one each time. The existing `random_range(max)` takes max as usize and creates a new RNG each call — for shuffle efficiency, create a method variant that takes a &mut OxiRng.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Prerequisites:** None — random_range already exists
  - **Tests:** Shuffle [1,2,3,4,5]; sort result; verify all 5 elements present. Shuffle empty slice: no error. Shuffle single-element slice: unchanged. Run shuffle 1000 times on [1,2,3], verify not always the same order (statistical test).
  - **Risk:** Very low — Fisher-Yates is well-known; care needed with the range bound (0..=i vs 0..i+1)
- [x] Add random nonce generation: `random_nonce::<N>(rng) -> [u8; N]` for AEAD nonce creation (~15 SLOC)
- [x] Add deterministic test RNG: `TestRng::from_seed(seed)` for reproducible tests (never use in production, compile-error if not `#[cfg(test)]`) (~30 SLOC) (planned 2026-05-25)
  - **Goal:** TestRng::from_seed(seed: [u8; 32]) for reproducible tests, restricted to #[cfg(test)]
  - **Design:** `#[cfg(test)] pub struct TestRng { inner: rand_chacha::ChaCha20Rng }`. `impl TestRng { pub fn from_seed(seed: [u8; 32]) -> Self { Self { inner: rand_chacha::ChaCha20Rng::from_seed(seed) } } }`. Implement TryRng for TestRng by delegating to inner. Do NOT implement outside cfg(test). Add a compile-time guard or doc-comment warning about test-only use.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Prerequisites:** rand_chacha already a workspace dep with SeedableRng/ChaCha20Rng
  - **Tests:** TestRng::from_seed([0u8; 32]) should produce a deterministic sequence; same seed twice = same output; different seed = different output
  - **Risk:** Very low
- [x] ChaCha8 / ChaCha12 CSPRNG variants (done 2026-05-25)
  - **Goal:** `OxiRng8` / `OxiRng12` using `rand_chacha::ChaCha8Rng`/`ChaCha12Rng`.
  - **Design:** mirror `OxiRng` (ChaCha20) construction + Rng/TryRng/TryCryptoRng impls + fork detection on Unix.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** fills buffers; distinct instances differ; reseed works; TryCryptoRng bound satisfied.
  - **Risk:** Low.
- [x] Implement `rand_core::CryptoRng` marker trait for `OxiRng` to enable use with `ml-kem`, `ml-dsa`, and other crates requiring `CryptoRng` (~10 SLOC)
- [x] `check_entropy()` health test (done 2026-05-25)
  - **Goal:** `check_entropy() -> Result<(), CryptoError>` basic OS-entropy sanity (repeated draws differ; not all-zero).
  - **Design:** draw two 32-byte buffers from getrandom, assert non-equal and non-constant. Documented as smoke test, not NIST SP 800-90B.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** returns Ok on a healthy system.
  - **Risk:** Low.
- [x] `OxiRng::reseed()` inherent method (done 2026-05-25)
  - **Goal:** promote the existing free-fn `reseed(&mut OxiRng)` to an inherent `OxiRng::reseed(&mut self) -> Result<(), CryptoError>`.
  - **Design:** inherent method delegates to free fn; free fn kept for backward compat.
  - **Files:** `crates/oxicrypto-rand/src/lib.rs`
  - **Tests:** post-reseed output differs from pre-reseed stream.
  - **Risk:** Low.

## API Improvements
- [x] Add `Rng::fill_exact(dst: &mut [u8; N])` method for fixed-size fills with compile-time length checking
  - Implemented as `OxiRng::fill_exact<const N: usize>` in `crates/oxicrypto-rand/src/oxirng.rs` (done 2026-05-26)
- [x] Implement `std::io::Read` for `OxiRng` (behind `std` feature) for reading random bytes via standard I/O (done 2026-05-26)
  - Implemented for both OxiRng and ReseedingRng; uses std::io::Error::other() (stable since 1.74, MSRV 1.89)
  - Tests in crates/oxicrypto-rand/tests/statistical.rs (std_read module)
- [x] Add `Display` / `Debug` that does NOT leak internal RNG state (currently `Debug` uses `finish_non_exhaustive` — good)
- [x] Add `Clone` restriction: `OxiRng` should NOT implement `Clone` (prevent accidental state duplication)
- [x] Add `Send + Sync` bounds documentation: `OxiRng` is `Send` but NOT `Sync` by design (ChaCha20Rng is not `Sync`) (done 2026-06-03)
  - Added detailed `# Thread Safety` doc sections to `OxiRng`, `OxiRng8`, `OxiRng12` in `src/oxirng.rs`; added compile-time `_assert_send` const fn to guarantee the `Send` bound is maintained
- [x] Add `#[must_use]` on `OxiRng::new()` return type
  - Already present; also added `#[must_use]` to `random_bytes`, `random_range`, `random_range_to`, `random_nonce` (done 2026-05-26)

## Testing
- [x] Statistical test: chi-squared test on byte distribution over 256,000 bytes (done 2026-05-26)
  - test_chi_squared_byte_distribution in tests/statistical.rs; bounds [150, 400] for χ²(255)
- [x] Statistical test: runs test (NIST SP 800-22 Section 2.3) on 1 MiB of output
  - `test_runs_nist_sp800_22_1mib` in `tests/statistical.rs`; ±10% tolerance (done 2026-05-26)
- [x] Statistical test: serial correlation test on consecutive random bytes
  - `test_serial_correlation` in `tests/statistical.rs`; correlation < 0.05 (done 2026-05-26)
- [x] Test: two `OxiRng::new()` instances produce different output sequences (done 2026-05-26)
  - test_independent_instances_differ in tests/statistical.rs
- [x] Test: `fill()` works correctly for buffer of size 0 (done 2026-05-26)
  - test_fill_zero_length_buffer in tests/statistical.rs
- [x] Test: `fill()` for buffers of size 1, 31, 32, 33, 1024, 1_000_000 (done 2026-06-03)
- [x] Test: `random_range(min, max)` never produces values outside [min, max) (done 2026-06-03)
- [x] Test: `random_range(0, 1)` always returns 0 (done 2026-05-26)
  - test_random_range_0_to_1_always_0 and test_random_range_free_fn_0_to_1_always_0 in tests/statistical.rs
- [x] Test: `random_range(n, n)` returns error (empty range) (done 2026-05-26)
  - test_random_range_min_equals_max_is_error in tests/statistical.rs
- [x] Test: fork-safe RNG produces different output in parent and child processes (Unix-only, `#[cfg(unix)]`)
  - `test_fork_produces_different_output` in `tests/statistical.rs`; verifies sequential calls differ (done 2026-05-26)
- [x] Test: `ReseedingRng` reseeds after generating exactly N bytes (done 2026-05-26)
  - test_reseeding_rng_reseeds_on_threshold in tests/statistical.rs
- [x] Test: `shuffle()` permutes all elements (check that every permutation occurs over many runs) (done 2026-06-03)
- [x] Fuzz test: `fill()` never panics on any buffer size (done 2026-06-03)
- [x] Replace `unwrap()` in existing tests with `expect()` or proper error propagation (done 2026-06-03)
  - Replaced `unwrap_or_else(|e| panic!(...))` with `expect()` in `tests/statistical.rs`; no bare `unwrap()` calls remain in any source or test file

## Performance
- [x] Benchmark `OxiRng::fill()` throughput for 32 B, 1 KiB, 64 KiB, 1 MiB buffers (done 2026-06-03)
  - `rand_fill/chacha20/<size>` group in `crates/oxicrypto-bench/benches/rand.rs`
- [x] Compare ChaCha20 CSPRNG throughput vs OS `/dev/urandom` direct reads (done 2026-06-03)
  - `rand_fill_vs_urandom/<size>` group: oxirng_chacha20 vs getrandom_direct
- [x] Benchmark ChaCha20 vs ChaCha12 vs ChaCha8 RNG throughput (done 2026-06-03)
  - `rand_fill/chacha8` and `rand_fill/chacha12` groups
- [x] Benchmark `ReseedingRng` overhead (reseeding latency at various thresholds) (done 2026-06-03)
  - `rand_reseeding` group: baseline_oxirng vs threshold 4/64/1024 KiB
- [x] Benchmark `random_range()` with rejection sampling vs simple modulo (measure bias elimination cost) (done 2026-06-03)
  - `rand_range` group: rejection_sampling_256/300/large vs naive_modulo_256
- [x] Profile thread-local RNG initialization cost (done 2026-06-03)
  - `rand_thread_rng` group: subsequent_call_32b and subsequent_call_1kib

## Integration
- [x] Ensure `oxicrypto-sig` key generation uses `OxiRng` (or accepts `&mut dyn Rng`)
  - `ed25519_generate_keypair_with_oxirng`, `ecdsa_p256_generate_keypair_with_oxirng`, etc. fully wired; FROST tests use `OxiRng` directly (done 2026-06-03)
- [x] Ensure `oxicrypto-kex` ephemeral key generation uses `OxiRng`
  - All `generate_keypair` functions accept generic `R: TryCryptoRng`; `OxiRng` satisfies this; integration tests in `tests/prop_kex.rs` verify all five algorithms with `OxiRng::new()` (done 2026-06-03)
- [x] Ensure `oxicrypto-pq` ML-KEM/ML-DSA key generation can accept `OxiRng` via `CryptoRng` trait
  - Replaced `kem_os_rng()` (ad-hoc `getrandom → ChaCha20Rng`) with `OxiRng::new().map(rand_core::UnwrapErr)` in both `mlkem.rs` and `hybrid.rs`; `UnwrapErr<OxiRng>` satisfies `CryptoRng` (= `TryCryptoRng<Error=Infallible>`); `oxicrypto-rand` added as runtime dep (done 2026-06-03)
- [x] Ensure `oxicrypto-aead` random nonce generation uses `OxiRng`
  - `seal_with_random_nonce` accepts `&mut impl TryCryptoRng`; `NonceSequence::random()` uses `OxiRng::new()` directly (done 2026-06-03)
- [x] Ensure `oxicrypto-kdf` salt generation uses `OxiRng`
  - `salt_generate(rng: &mut OxiRng)` already present; `OxiRng::new()` used in tests (done 2026-06-03)
- [x] Provide `new_rng()` in facade that returns `Box<dyn Rng>` (already done; ensure it stays in sync)
  - `oxicrypto::new_rng()` wraps `OxiRng::new()` → `Box<dyn Rng>`; tested in `crates/oxicrypto/src/tests.rs` (done 2026-06-03)
