canic_utils/
rand.rs

1//!
2//! Canister-local deterministic PRNG seeded externally (e.g. via `raw_rand`).
3//!
4//! The IC executes canister code single-threaded, so `RefCell` provides
5//! sufficient interior mutability without locking.
6//!
7//! The RNG must be explicitly seeded before use (typically during init or
8//! post-upgrade) and is intended for update calls where state advancement
9//! is permitted.
10//!
11
12use rand_chacha::{
13    ChaCha20Rng,
14    rand_core::{Rng, SeedableRng},
15};
16use std::cell::RefCell;
17use thiserror::Error as ThisError;
18
19thread_local! {
20    static RNG: RefCell<Option<ChaCha20Rng>> = const { RefCell::new(None) };
21}
22
23// -----------------------------------------------------------------------------
24// Errors
25// -----------------------------------------------------------------------------
26
27///
28/// RngError
29/// Errors raised when randomness is unavailable.
30///
31
32#[derive(Debug, ThisError)]
33pub enum RngError {
34    #[error("Randomness is not initialized. Please try again later")]
35    NotInitialized,
36}
37
38// -----------------------------------------------------------------------------
39// Seeding
40// -----------------------------------------------------------------------------
41
42/// Seed the RNG with a 32-byte value (e.g. management canister `raw_rand` output).
43pub fn seed_from(seed: [u8; 32]) {
44    RNG.with_borrow_mut(|rng| {
45        *rng = Some(ChaCha20Rng::from_seed(seed));
46    });
47}
48
49/// Returns true if the RNG has been seeded.
50#[must_use]
51pub fn is_seeded() -> bool {
52    RNG.with_borrow(Option::is_some)
53}
54
55fn with_rng<T>(f: impl FnOnce(&mut ChaCha20Rng) -> T) -> Result<T, RngError> {
56    RNG.with_borrow_mut(|rng| match rng.as_mut() {
57        Some(rand) => Ok(f(rand)),
58        None => Err(RngError::NotInitialized),
59    })
60}
61
62// -----------------------------------------------------------------------------
63// Random bytes
64// -----------------------------------------------------------------------------
65
66/// Fill the provided buffer with random bytes.
67pub fn fill_bytes(dest: &mut [u8]) -> Result<(), RngError> {
68    with_rng(|rand| rand.fill_bytes(dest))
69}
70
71/// Produce random bytes using the shared RNG.
72pub fn random_bytes(size: usize) -> Result<Vec<u8>, RngError> {
73    let mut buf = vec![0u8; size];
74    fill_bytes(&mut buf)?;
75    Ok(buf)
76}
77
78/// Produce an 8-bit random value (derived from `next_u16`).
79pub fn next_u8() -> Result<u8, RngError> {
80    Ok((next_u16()? & 0xFF) as u8)
81}
82
83/// Produce a 16-bit random value from the shared RNG.
84#[expect(clippy::cast_possible_truncation)]
85pub fn next_u16() -> Result<u16, RngError> {
86    with_rng(|rand| rand.next_u32() as u16)
87}
88
89/// Produce a 32-bit random value from the shared RNG.
90pub fn next_u32() -> Result<u32, RngError> {
91    with_rng(Rng::next_u32)
92}
93
94/// Produce a 64-bit random value from the shared RNG.
95pub fn next_u64() -> Result<u64, RngError> {
96    with_rng(Rng::next_u64)
97}
98
99/// Produce a 128-bit random value from the shared RNG.
100pub fn next_u128() -> Result<u128, RngError> {
101    with_rng(|rand| {
102        let hi = u128::from(rand.next_u64());
103        let lo = u128::from(rand.next_u64());
104        (hi << 64) | lo
105    })
106}
107
108///
109/// TESTS
110///
111
112#[cfg(test)]
113mod tests {
114    use super::*;
115
116    #[test]
117    fn test_unique_u64s() {
118        use std::collections::HashSet;
119
120        seed_from([7; 32]);
121
122        let mut set = HashSet::new();
123        while set.len() < 1000 {
124            let random_value = next_u64().expect("seeded RNG");
125            assert!(set.insert(random_value), "value already in set");
126        }
127    }
128
129    #[test]
130    fn test_rng_reseeding() {
131        seed_from([1; 32]);
132        let first = next_u64().expect("seeded RNG");
133        seed_from([2; 32]);
134        let second = next_u64().expect("seeded RNG");
135
136        assert_ne!(
137            first, second,
138            "RNGs with different seeds unexpectedly produced the same value"
139        );
140    }
141
142    #[test]
143    fn test_determinism_with_fixed_seed() {
144        let seed = [42u8; 32];
145        seed_from(seed);
146
147        let values: Vec<u64> = (0..100).map(|_| next_u64().expect("seeded RNG")).collect();
148
149        seed_from(seed);
150        for value in values {
151            assert_eq!(next_u64().expect("seeded RNG"), value);
152        }
153    }
154
155    #[test]
156    fn test_missing_seed_errors() {
157        RNG.with_borrow_mut(|rng| {
158            *rng = None;
159        });
160
161        assert!(matches!(random_bytes(8), Err(RngError::NotInitialized)));
162    }
163
164    // Sanity check only: ensures bits vary across samples.
165    // This is not a statistical entropy test.
166    #[test]
167    fn test_bit_entropy() {
168        seed_from([3; 32]);
169
170        let mut bits = 0u64;
171        for _ in 0..100 {
172            bits |= next_u64().expect("seeded RNG");
173        }
174
175        let bit_count = bits.count_ones();
176        assert!(
177            bit_count > 8,
178            "Low entropy: only {bit_count} bits set in 100 samples",
179        );
180    }
181}
canic_utils/rand.rs

canic_utils/
rand.rs
