Secure Randomness

17 min read

Not all random numbers are equal. The generator behind your dice roll in a game is a poor choice for a session token, a password-reset link, or an encryption key. This topic shows how Rust separates fast-but-predictable randomness from cryptographically secure randomness, and how to reach for the right one.

Quick Overview

A cryptographically secure pseudo-random number generator (CSPRNG) produces output that an attacker cannot predict or reproduce, even after observing many prior outputs. Anything that becomes a secret — session IDs, CSRF tokens, API keys, salts, nonces, reset links — must come from a CSPRNG seeded by the operating system’s entropy pool.

The good news for TypeScript/JavaScript developers: Rust’s standard randomness crate (rand) is secure by default. Its thread-local generator is a CSPRNG, and the foundation crate (getrandom) talks directly to the OS (getrandom(2) on Linux, BCryptGenRandom on Windows, getentropy on macOS). The danger is the opposite of JavaScript: in JS the convenient Math.random() is the insecure one and you must remember to switch to crypto; in Rust you have to go out of your way to pick a non-secure generator like SmallRng.

Note: This file is about generating random bytes securely. Hashing those bytes (passwords) lives in password-hashing.md, and using them as keys/nonces for encryption lives in cryptography.md.

TypeScript/JavaScript Example

In Node.js, Math.random() is not cryptographically secure — it is a fast PRNG (V8 uses xorshift128+) seeded once at startup. Using it for anything security-sensitive is a real, common vulnerability. The secure path is the node:crypto module.

1
import { randomBytes, randomInt, randomUUID } from "node:crypto";
2

3
// INSECURE: Math.random() is predictable. NEVER use it for secrets.
4
function weakToken(): string {
5
  let s = "";
6
  for (let i = 0; i < 32; i++) {
7
    s += Math.floor(Math.random() * 16).toString(16);
8
  }
9
  return s; // an attacker who learns the seed can reproduce every token
10
}
11

12
// SECURE: node:crypto is backed by the OS CSPRNG.
13
function sessionToken(): string {
14
  return randomBytes(32).toString("hex"); // 256 bits of real entropy
15
}
16

17
// A 6-digit one-time code, unbiased, from the secure source.
18
function otpCode(): string {
19
  return randomInt(0, 1_000_000).toString().padStart(6, "0");
20
}
21

22
console.log("weak   :", weakToken());
23
console.log("session:", sessionToken());
24
console.log("otp    :", otpCode());
25
console.log("uuid   :", randomUUID()); // v4 UUID, also crypto-backed

Running this under Node v22 prints something like:

1
weak   : 7a3c0f9e1b...        (predictable — do not use)
2
session: 8049bcbf450e98a95fe346ba408f71fc...   (64 hex chars = 32 bytes)
3
otp    : 090096
4
uuid   : 78432f6b-7d49-4050-8f6a-114605c45d02

Key points:

Math.random() returns an IEEE-754 f64 in [0, 1) and is not secure. It is fine for shuffling a UI carousel; it is a vulnerability for a token.
crypto.randomBytes, crypto.randomInt, and crypto.randomUUID are the secure, OS-backed APIs. In the browser the equivalent is crypto.getRandomValues / crypto.randomUUID.
The footgun is that the easy-to-type function is the insecure one.

Rust Equivalent

In Rust the defaults are inverted: the convenient rand::rng() (the thread-local generator) is already a CSPRNG, and getrandom/SysRng go straight to the OS. You have to deliberately choose SmallRng to get a non-secure generator.

The examples below use the current rand crate. Add it to a project with:

1
cargo add rand

This resolves to rand = "0.10" (the current stable line; 0.10.1 at the time of writing). The API changed meaningfully across 0.8 → 0.9 → 0.10, so code you find online may not match — the snippets here are written and compiled against 0.10.

1
use rand::{rng, RngExt};        // RngExt provides the ergonomic .random* methods
2
use rand::rngs::SysRng;         // SysRng = the OS CSPRNG (called OsRng before 0.10)
3
use rand::TryRng;               // SysRng's fill is fallible, via try_fill_bytes
4

5
fn main() {
6
    // The thread-local CSPRNG: auto-seeded from the OS, periodically reseeded.
7
    // This is the right default for almost everything.
8
    let mut r = rng();
9
    let n: u32 = r.random();
10
    let dice: u8 = r.random_range(1..=6);
11
    println!("random u32 = {n}");
12
    println!("dice = {dice}");
13

14
    // Fill a buffer with random bytes (infallible on the thread RNG).
15
    let mut token = [0u8; 16];
16
    r.fill(&mut token[..]);
17
    println!("token len = {}", token.len());
18

19
    // Convenience free functions — they use the thread RNG under the hood.
20
    let coin = rand::random::<bool>();
21
    let pct: u8 = rand::random_range(0..=100);
22
    println!("coin = {coin}, pct = {pct}");
23

24
    // SysRng: bytes straight from the OS, no userspace PRNG state.
25
    // OS calls can fail, so the API is fallible (try_fill_bytes).
26
    let mut key = [0u8; 32];
27
    SysRng.try_fill_bytes(&mut key).expect("OS entropy unavailable");
28
    println!("key first byte = {}", key[0]);
29
}

Real output from one run (your values will differ — that is the point):

1
random u32 = 474142268
2
dice = 5
3
token len = 16
4
coin = true, pct = 70
5
key first byte = 241

There is no insecure-by-accident path here. rng(), SysRng, and the rand::random* free functions are all cryptographically secure.

Detailed Explanation

rng() — the everyday CSPRNG. rand::rng() returns a ThreadRng, a handle to a thread-local generator. On first use it is seeded from the operating system (SysRng), then it produces output with the ChaCha12 stream cipher and reseeds itself periodically. It is a CSPRNG, it requires no setup, and because it is thread-local it is fast (no syscall per number). This is the JS crypto-quality default, but with the ergonomics of Math.random().

RngExt — where the methods live. In rand 0.10 the trait you import for .random(), .random_range(), and .fill() is RngExt (it was simply Rng in 0.8/0.9). The bare Rng trait still exists but is now the low-level “produce raw words” trait (the old RngCore). If you forget use rand::RngExt;, the compiler tells you exactly which trait to import (see Common Pitfalls).

random() vs random_range(). random::<T>() fills a value of type T from the full range of its StandardUniform distribution (every u32, a bool, a tuple, etc.). random_range(1..=6) maps the bytes into a bounded range. By default random_range uses a fast widening-multiply method that has a tiny statistical bias; enabling the crate’s unbiased feature switches it to rejection sampling for perfectly uniform output. For dice and OTPs this default bias is negligible; if you need provably uniform sampling (e.g. drawing a card for a regulated game), enable unbiased.

SysRng — the operating system source. SysRng (re-exported from getrandom) is a stateless interface to the OS entropy source. Every call is essentially a syscall, so it is slower than ThreadRng but never holds predictable userspace state. Because OS calls can fail (a sandbox with no getrandom, an extremely early boot), its fill method is try_fill_bytes, returning a Result. This is why it lives behind the TryRng trait rather than the infallible Rng trait.

getrandom — the foundation. Underneath everything sits the getrandom crate, which is the portable shim over each platform’s OS CSPRNG. You rarely call it directly, but it is the reason rand is secure by default and works on no_std and WebAssembly targets.

1
fn main() {
2
    // Lowest level: bytes straight from the OS, no PRNG abstraction at all.
3
    let mut seed = [0u8; 32];
4
    getrandom::fill(&mut seed).expect("OS entropy unavailable");
5
    let n: u32 = getrandom::u32().expect("OS entropy unavailable");
6
    println!("seed byte 0 = {}, n = {n}", seed[0]);
7
}

Real output:

1
seed byte 0 = 102, n = 2173754844

SmallRng and StdRng — the explicit choices. SmallRng is a small, fast, non-cryptographic PRNG for simulations and benchmarks. StdRng is the same CSPRNG algorithm that backs ThreadRng, but you own the instance — useful when you want a seedable secure generator. Critically, only secure generators implement the CryptoRng marker trait, which lets you encode “I require secure randomness” directly in a function signature (shown below).

Key Differences

Concern	TypeScript / Node.js	Rust (`rand` 0.10)
Convenient default	`Math.random()` — insecure	`rng()` — secure (CSPRNG)
Secure source	`node:crypto` (`randomBytes`, `randomInt`)	`rng()`, `SysRng`, `getrandom::fill`
Insecure source	`Math.random()` (always there)	`SmallRng` (must opt in)
Bytes into a buffer	`randomBytes(n)` → `Buffer`	`rng().fill(&mut buf)` / `SysRng.try_fill_bytes`
Bounded integer	`crypto.randomInt(0, n)`	`rng().random_range(0..n)`
UUID v4	`crypto.randomUUID()`	`uuid` crate, `Uuid::new_v4()`
Secure-only at the type level	not expressible	`R: CryptoRng` bound
Failure handling	throws	`SysRng` returns `Result` (fallible)

The deepest difference is the type-level guarantee. In JavaScript nothing stops you from passing the output of Math.random() where a secret is expected — it is all number. In Rust you can write a function that only accepts a cryptographically secure generator, and the compiler rejects a fast non-secure one:

1
use rand::{RngExt, SeedableRng, CryptoRng};
2
use rand::rngs::{StdRng, SmallRng, SysRng};
3

4
// Accepts ONLY a cryptographically secure RNG — enforced at compile time.
5
fn make_token<R: CryptoRng>(rng: &mut R) -> [u8; 16] {
6
    let mut buf = [0u8; 16];
7
    rng.fill(&mut buf[..]);
8
    buf
9
}
10

11
fn main() {
12
    // StdRng seeded from the OS IS a CryptoRng — accepted.
13
    let mut secure = StdRng::try_from_rng(&mut SysRng).expect("OS entropy");
14
    let token = make_token(&mut secure);
15
    println!("token byte 0 = {}", token[0]);
16

17
    // SmallRng is fast but NOT cryptographic — fine for simulations only.
18
    let mut fast = SmallRng::seed_from_u64(7);
19
    let x: u64 = fast.random();
20
    println!("non-crypto value = {x}");
21
    // make_token(&mut fast); // would NOT compile — see Common Pitfalls
22
}

Real output:

1
token byte 0 = 246
2
non-crypto value = 1021219803524665661

This is “make illegal states unrepresentable” applied to entropy — the same parse-don’t-validate idea explored in input-validation.md, but for randomness quality.

Common Pitfalls

Pitfall 1: Forgetting to import `RngExt`

The ergonomic methods live on a trait, and the method is invisible until that trait is in scope. This is the single most common confusion for newcomers (and for anyone copying rand 0.8 code).

1
use rand::rng;   // forgot: use rand::RngExt;
2

3
fn main() {
4
    let mut r = rng();
5
    let n: u32 = r.random();   // does not compile (error[E0599]: no method named `random`)
6
    println!("{n}");
7
}

The real compiler output points straight at the fix:

1
error[E0599]: no method named `random` found for struct `ThreadRng` in the current scope
2
 --> src/main.rs:5:20
3
  |
4
5 |     let n: u32 = r.random();   //
5
  |                    ^^^^^^
6
  |
7
  = help: items from traits can only be used if the trait is in scope
8
help: trait `RngExt` which provides `random` is implemented but not in scope; perhaps you want to import it
9
  |
10
1 + use rand::RngExt;

Add use rand::RngExt; (or use rand::prelude::*;, which pulls in RngExt, SeedableRng, and the common generators) and it compiles.

Pitfall 2: Using a non-CSPRNG (or a fixed seed) for a secret

SmallRng is fast and great for Monte-Carlo work, but it is not secure — its output is predictable from a small amount of observed data, and worse, code often seeds it with a constant. If you try to use a non-secure generator where a CryptoRng is required, the compiler stops you:

1
use rand::{RngExt, SeedableRng, CryptoRng};
2
use rand::rngs::SmallRng;
3

4
fn make_token<R: CryptoRng>(rng: &mut R) -> [u8; 16] {
5
    let mut buf = [0u8; 16];
6
    rng.fill(&mut buf[..]);
7
    buf
8
}
9

10
fn main() {
11
    let mut fast = SmallRng::seed_from_u64(7);
12
    let _token = make_token(&mut fast);   // does not compile (error[E0277])
13
}

The real error spells out that SmallRng is not cryptographic:

1
error[E0277]: the trait bound `SmallRng: CryptoRng` is not satisfied
2
  --> src/main.rs:12:29
3
   |
4
12 |     let _token = make_token(&mut fast);   //
5
   |                  ---------- ^^^^^^^^^ ...
6
   |
7
   = note: required for `SmallRng` to implement `TryCryptoRng`
8
   = note: required for `SmallRng` to implement `CryptoRng`
9
note: required by a bound in `make_token`

The takeaway: bound your security-sensitive helpers on CryptoRng so this class of mistake cannot reach production. A SmallRng::seed_from_u64(7) would otherwise compile happily and produce the same token on every run — a catastrophic auth bug.

Pitfall 3: Comparing secret tokens with `==`

Generating a token securely is only half the job. Verifying it with the ordinary == operator leaks length and prefix information through timing, because == returns as soon as it finds the first differing byte. Compare in constant time with the subtle crate (cargo add subtle):

1
use subtle::ConstantTimeEq;
2

3
fn tokens_match(stored: &str, candidate: &str) -> bool {
4
    // Returns false fast on length mismatch, then compares bytes in constant time.
5
    stored.as_bytes().ct_eq(candidate.as_bytes()).into()
6
}
7

8
fn main() {
9
    let stored = "uVnwjGNJWAL_bhnr3QywCwwpNeelGKSJquMt1U3hZf0";
10
    println!("correct  = {}", tokens_match(stored, stored));
11
    println!("tampered = {}", tokens_match(stored, "not-the-token"));
12
}

Real output:

1
correct  = true
2
tampered = false

Warning: Timing-safe comparison matters for any secret you compare against attacker-supplied input — tokens, HMAC tags, API keys. It does not substitute for hashing: see cryptography.md for the full picture.

Pitfall 4: Too few bytes

A “random” token is only as strong as its entropy. A 4-byte (32-bit) token has only ~4 billion possibilities — brute-forceable. Use at least 16 bytes (128 bits) for tokens, and 32 bytes (256 bits) when in doubt. Bytes are cheap.

Best Practices

Default to rand::rng(). It is a CSPRNG, requires no setup, and is fast. Reach for SysRng/getrandom only when you specifically want a stateless OS source (e.g. generating a one-off key with no thread-local generator around).
Use SmallRng only for non-security work, and say so in a comment. Simulations, fuzz inputs, procedural generation — fine. Tokens, keys, salts, nonces — never.
Encode the requirement in types. Make security-sensitive functions generic over R: CryptoRng (or just take &mut impl CryptoRng). The compiler then forbids passing a SmallRng.
Generate at least 128 bits of entropy for tokens; 256 bits for long-lived secrets.
Encode for transport, don’t shrink. Turn raw bytes into hex (hex crate) or URL-safe base64 (base64 crate) for cookies and links — never truncate the entropy to make it “look nicer.”
Compare secrets in constant time with subtle::ConstantTimeEq.
Don’t seed a CSPRNG from a timestamp, PID, or counter. That defeats the entire point; let it seed from the OS.
For UUIDs, use the uuid crate with Uuid::new_v4() (it pulls entropy from getrandom) rather than assembling one by hand.

Real-World Example

A production-grade, single-use token type — the kind you would hand out for a password-reset or email-confirmation link. It generates 256 bits of OS entropy, encodes it URL-safe so it can live in a query string, and verifies in constant time.

Dependencies (cargo add rand base64 subtle getrandom):

1
[dependencies]
2
rand = "0.10"
3
base64 = "0.22"
4
subtle = "2.6"
5
getrandom = "0.4"

1
use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
2
use rand::rngs::SysRng;
3
use rand::TryRng;
4
use subtle::ConstantTimeEq;
5

6
/// A short-lived, single-use token (password reset, email confirmation, ...).
7
#[derive(Clone)]
8
struct ResetToken(String);
9

10
impl ResetToken {
11
    /// 256 bits of OS entropy, URL-safe so it can go directly in a link.
12
    fn generate() -> Result<Self, getrandom::Error> {
13
        let mut bytes = [0u8; 32];
14
        SysRng.try_fill_bytes(&mut bytes)?;        // OS CSPRNG; fallible
15
        Ok(Self(URL_SAFE_NO_PAD.encode(bytes)))
16
    }
17

18
    /// Compare against a candidate in constant time (no timing side channel).
19
    fn matches(&self, candidate: &str) -> bool {
20
        self.0.as_bytes().ct_eq(candidate.as_bytes()).into()
21
    }
22

23
    fn as_str(&self) -> &str {
24
        &self.0
25
    }
26
}
27

28
fn main() -> Result<(), getrandom::Error> {
29
    let token = ResetToken::generate()?;
30

31
    println!(
32
        "reset link: https://app.example.com/reset?token={}",
33
        token.as_str()
34
    );
35
    println!("token length (chars) = {}", token.as_str().len());
36
    println!("correct match  = {}", token.matches(token.as_str()));
37
    println!("tampered match = {}", token.matches("not-the-token"));
38
    Ok(())
39
}

Real output (the token differs every run — exactly what you want):

1
reset link: https://app.example.com/reset?token=uVnwjGNJWAL_bhnr3QywCwwpNeelGKSJquMt1U3hZf0
2
token length (chars) = 43
3
correct match  = true
4
tampered match = false

In a real service you would store a hash of this token (see password-hashing.md) so a database leak does not expose live reset links, deliver it over TLS (see tls-ssl.md), and keep the value out of your logs (see secrets-management.md).

Exercises

Exercise 1: Secure API key generator

Difficulty: Beginner

Objective: Get comfortable with the secure default generator and byte encoding.

Instructions: Write a function api_key() -> String that returns a 24-byte (192-bit) key encoded as lowercase hex (so 48 characters). Use the thread-local CSPRNG. Add the hex crate with cargo add hex. Print three keys from main and confirm they differ on every run.

Solution

1
// cargo add rand hex
2
use rand::{rng, RngExt};
3

4
fn api_key() -> String {
5
    let mut bytes = [0u8; 24];     // 192 bits of entropy
6
    rng().fill(&mut bytes[..]);    // ThreadRng is a CSPRNG
7
    hex::encode(bytes)             // 48 lowercase hex chars
8
}
9

10
fn main() {
11
    for _ in 0..3 {
12
        let key = api_key();
13
        println!("key = {key} ({} chars)", key.len());
14
    }
15
}

Real output (different every run):

1
key = 4c264f9695fb29d591cd6e9dbc7bcc6aba4eb4bc4614b8bd (48 chars)
2
key = a1f0...  (48 chars)
3
key = 7e93...  (48 chars)

Exercise 2: A zero-padded one-time code

Difficulty: Intermediate

Objective: Generate an unbiased bounded integer from a secure source and format it.

Instructions: Write otp_code() -> String that returns a 6-digit numeric one-time code, zero-padded (so 42 becomes "000042"). Use random_range on the thread RNG. Bonus: explain in a comment why drawing a u32 in 0..1_000_000 and formatting is better than rng().random::<u32>() % 1_000_000.

Solution

1
// cargo add rand
2
use rand::{rng, RngExt};
3

4
/// A 6-digit numeric one-time code, zero-padded.
5
fn otp_code() -> String {
6
    // random_range maps entropy into 0..1_000_000 cleanly.
7
    // Doing `random::<u32>() % 1_000_000` introduces modulo bias because
8
    // 2^32 is not a multiple of 1_000_000, so low codes are slightly more
9
    // likely. random_range avoids that (and the `unbiased` feature removes
10
    // even the residual bias entirely).
11
    let n: u32 = rng().random_range(0..1_000_000);
12
    format!("{n:06}")
13
}
14

15
fn main() {
16
    for _ in 0..3 {
17
        println!("{}", otp_code());
18
    }
19
}

Real output:

Exercise 3: Enforce secure randomness at the type level

Difficulty: Advanced

Objective: Use the CryptoRng bound so misuse is a compile error, and prove it.

Instructions: Write fn nonce<R: CryptoRng>(rng: &mut R) -> [u8; 12] that fills a 12-byte nonce. Call it from main with a secure generator (StdRng::try_from_rng(&mut SysRng)). Then add a commented-out line that tries to call it with SmallRng and, in a comment, paste or paraphrase the error you get when you uncomment it. Explain why this matters for AEAD nonces.

Solution

1
// cargo add rand
2
use rand::{RngExt, SeedableRng, CryptoRng};
3
use rand::rngs::{StdRng, SmallRng, SysRng};
4

5
/// Produce a 12-byte nonce. The CryptoRng bound forbids non-secure RNGs.
6
fn nonce<R: CryptoRng>(rng: &mut R) -> [u8; 12] {
7
    let mut buf = [0u8; 12];
8
    rng.fill(&mut buf[..]);
9
    buf
10
}
11

12
fn main() {
13
    // Secure: StdRng seeded from the OS implements CryptoRng.
14
    let mut secure = StdRng::try_from_rng(&mut SysRng).expect("OS entropy");
15
    let n = nonce(&mut secure);
16
    println!("nonce = {n:?}");
17

18
    // Insecure: SmallRng is NOT a CryptoRng. Uncommenting this fails to compile:
19
    let mut _fast = SmallRng::seed_from_u64(7);
20
    // let _bad = nonce(&mut _fast);
21
    // error[E0277]: the trait bound `SmallRng: CryptoRng` is not satisfied
22
    //   = note: required for `SmallRng` to implement `CryptoRng`
23
    //   note: required by a bound in `nonce`
24
}

Real output (the uncommented program runs cleanly; values differ each run):

1
nonce = [188, 51, 9, 247, 22, 130, 64, 201, 78, 5, 233, 17]

Why it matters: AEAD ciphers (AES-GCM, ChaCha20-Poly1305) require a nonce that is never reused under the same key — a repeated nonce can leak plaintext and even the authentication key. A predictable generator like a fixed-seed SmallRng would hand out the same nonce sequence on every process start, which is exactly the kind of catastrophic reuse the CryptoRng bound prevents at compile time. The encryption side of this is covered in cryptography.md.

Secure Randomness

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

Pitfall 1: Forgetting to import RngExt

Pitfall 2: Using a non-CSPRNG (or a fixed seed) for a secret

Pitfall 3: Comparing secret tokens with ==

Pitfall 4: Too few bytes

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Secure API key generator

Exercise 2: A zero-padded one-time code

Exercise 3: Enforce secure randomness at the type level

Pitfall 1: Forgetting to import `RngExt`

Pitfall 3: Comparing secret tokens with `==`