Random and pseudo-random

OS-backed entropy sources plus refcounted PRNG objects. More...

Macros
#define	r_rand_std_srand(seed)   srand (seed)
	Seed the C-library rand() with seed.
#define	r_rand_std_rand()   rand ()
	Single sample from the C-library rand().
#define	r_rand_prng_new   r_prng_new_kiss
	Default PRNG constructor (currently KISS).
#define	r_prng_ref   r_ref_ref
	Take a reference (alias for r_ref_ref).
#define	r_prng_unref   r_ref_unref
	Drop a reference (alias for r_ref_unref).

Typedefs
typedef struct RPrng	RPrng
	Opaque, refcounted PRNG handle.

Functions
rboolean	r_rand_entropy_fill (ruint8 *buf, rsize size)
	Fill buf with size bytes of cryptographic-grade OS entropy.
ruint64	r_rand_entropy_u64 (void)
	Read a 64-bit value from the OS entropy source.
ruint32	r_rand_entropy_u32 (void)
	Read a 32-bit value from the OS entropy source.
ruint64	r_prng_get_u64 (RPrng *prng)
	Draw a 64-bit sample from prng.
rboolean	r_prng_fill (RPrng *prng, ruint8 *buf, rsize size)
	Fill buf with size pseudo-random bytes from prng.
rboolean	r_prng_fill_nonzero (RPrng *prng, ruint8 *buf, rsize size)
	Like r_prng_fill, but every byte is guaranteed non-zero.
rboolean	r_prng_fill_base64 (RPrng *prng, rchar *buf, rsize size)
	Fill buf with size base64-alphabet characters; useful for token / nonce generation.

PRNG constructors
RPrng *	r_prng_new_crypto (void)
	Cryptographically-secure PRNG: a ChaCha20 DRBG seeded from the OS entropy source and periodically reseeded.
RPrng *	r_prng_new_system (void)
	Cryptographically-secure PRNG that reads every output directly from the OS entropy source (see r_rand_entropy_fill).
RPrng *	r_prng_new_kiss (void)
	KISS PRNG seeded from OS entropy.
RPrng *	r_prng_new_kiss_with_seed (ruint64 x, ruint64 y, ruint64 z, ruint64 c)
	KISS PRNG with explicit four-component seed.
RPrng *	r_prng_new_mt (void)
	Mersenne Twister PRNG seeded from OS entropy.
RPrng *	r_prng_new_mt_with_seed (ruint64 seed)
	Mersenne Twister PRNG seeded from a single 64-bit value.
RPrng *	r_prng_new_mt_with_seed_array (const ruint64 *array, rsize size)
	Mersenne Twister PRNG seeded from an array of 64-bit values (recommended for reproducing a specific state).

Detailed Description

OS-backed entropy sources plus refcounted PRNG objects.

Three tiers, by intended use:

• Raw OS entropy — r_rand_entropy_fill (and the r_rand_entropy_u32 / r_rand_entropy_u64 scalar helpers) read straight from the OS CSPRNG (getrandom / getentropy, CryptGenRandom on Windows, or /dev/urandom as a fallback).
• Crypto-grade PRNG — r_prng_new_crypto (a ChaCha20 DRBG) and r_prng_new_system (a direct OS pass-through). Use these for any key, nonce or secret.
• Statistical PRNGs — r_prng_new_kiss and r_prng_new_mt are fast, well-distributed and seedable for reproducibility, but not cryptographically secure.

Warning

The KISS and Mersenne Twister PRNGs are statistical, not cryptographic — their internal state is recoverable from their output. Never use them for cryptographic keys or nonces; use r_prng_new_crypto instead.

Note

An individual RPrng instance is not safe for concurrent use: drawing from one updates its internal state without locking. Give each thread its own instance, or serialise access.

Function Documentation

r_prng_new_crypto()

RPrng * r_prng_new_crypto

(

void

)

Cryptographically-secure PRNG: a ChaCha20 DRBG seeded from the OS entropy source and periodically reseeded.

This is the recommended source for cryptographic keys and nonces. It applies fast key erasure (forward secrecy) and reseeds from the OS after a bounded number of output bytes, combining the throughput of a userspace stream cipher with the unpredictability of the OS entropy pool.

Returns

A new PRNG, or NULL on allocation / entropy failure.

r_prng_new_kiss()

RPrng * r_prng_new_kiss

(

void

)

KISS PRNG seeded from OS entropy.

Warning

Statistical only — not cryptographically secure. Use r_prng_new_crypto for keys or nonces.

r_prng_new_mt()

RPrng * r_prng_new_mt

(

void

)

Mersenne Twister PRNG seeded from OS entropy.

Warning

Statistical only — not cryptographically secure. Use r_prng_new_crypto for keys or nonces.

r_prng_new_system()

RPrng * r_prng_new_system

(

void

)

Cryptographically-secure PRNG that reads every output directly from the OS entropy source (see r_rand_entropy_fill).

Slower than r_prng_new_crypto but holds no userspace state. Aborts the process if the OS source ever fails to deliver entropy, so callers never silently receive predictable output.

Returns

A new PRNG, or NULL on allocation failure.

r_rand_entropy_fill()

rboolean r_rand_entropy_fill	(	ruint8 *	buf,
		rsize	size
	)

Fill buf with size bytes of cryptographic-grade OS entropy.

Reads from the OS CSPRNG, preferring the getrandom / getentropy syscalls (or CryptGenRandom on Windows) and falling back to /dev/urandom.

Unlike r_rand_entropy_u32 / r_rand_entropy_u64, this makes no fallback: it returns FALSE if the OS source cannot deliver the full request, so it is safe to use for keys and nonces.

Parameters

buf	Destination buffer.
size	Number of bytes to fill.

Returns

TRUE if all size bytes were filled from the OS source.

r_rand_entropy_u32()

ruint32 r_rand_entropy_u32

(

void

)

Read a 32-bit value from the OS entropy source.

Note

Same monotonic-timestamp fallback caveat as r_rand_entropy_u64.

r_rand_entropy_u64()

ruint64 r_rand_entropy_u64

(

void

)

Read a 64-bit value from the OS entropy source.

Note

Falls back to a monotonic timestamp if the OS source is unavailable, so it is suitable for seeding statistical PRNGs but not for cryptographic use — prefer r_rand_entropy_fill there.