ppad-random-0.1.0: Fast random number generators.
Copyright(c) 2026 Jared Tobin
LicenseMIT
MaintainerJared Tobin <jared@ppad.tech>
Safe HaskellNone
LanguageHaskell2010

Crypto.CSPRNG

Description

A fast cryptographically-secure pseudorandom number generator: ChaCha8Rand, as used by Go's mathrandv2 and runtime.

The generator draws 992 bytes of output at a time from ChaCha8, and rekeys itself from the next 32 bytes. Its key and output buffer are erased as they are used, and the native ChaCha8 kernels (on aarch64 and x86_64) zero the stack they use, so that a later disclosure of the process's memory reveals nothing about prior output. This covers the generator's own state only: copies of seeds passed to it and of output it returns are the caller's to manage, and on other platforms the pure Haskell ChaCha8 fallback makes copies of keys and keystream that the garbage collector manages and can't erase.

The generator is mutable, living in any PrimMonad (e.g. IO or 'ST s'), and is not thread-safe. Use one generator per thread, deriving more via split.

A forked process (e.g. via forkProcess), or a restored virtual machine snapshot, inherits a copy of the generator's state, and then produces the same output as the original. Create a new generator in such a child, e.g. via new_system, rather than using an inherited one.

Synopsis

Generator

data Gen s Source #

A ChaCha8Rand generator.

new :: PrimMonad m => ByteString -> m (Maybe (Gen (PrimState m))) Source #

Create a generator from a 256-bit seed, returning Nothing if the seed is not exactly 32 bytes.

The seed must be secret and uniformly random; prefer new_system unless a reproducible stream is required.

>>> Just gen <- new "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456"
>>> word64 gen
13219109469176600229

new_system :: IO (Maybe (Gen RealWorld)) Source #

Create a generator seeded from the operating system's entropy source, returning Nothing if that fails.

>>> Just gen <- new_system

Output

word64 :: PrimMonad m => Gen (PrimState m) -> m Word64 Source #

Generate a uniformly-distributed Word64 from the next eight bytes of output, read in little-endian order. If a call to bytes has left the output out of eight-byte alignment, the bytes up to the next boundary are discarded.

>>> Just gen <- new "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456"
>>> word64 gen
13219109469176600229

word64_range :: PrimMonad m => Word64 -> Word64 -> Gen (PrimState m) -> m Word64 Source #

Generate a uniformly-distributed Word64 in the given inclusive range, whose bounds may be given in either order.

The result is unbiased; see int_range.

>>> Just gen <- new "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456"
>>> word64_range 1 6 gen
5

int_range :: PrimMonad m => Int -> Int -> Gen (PrimState m) -> m Int Source #

Generate a uniformly-distributed Int in the given inclusive range, whose bounds may be given in either order.

The result is unbiased, via Lemire's method: an occasional draw is rejected and replaced, so the number of words consumed, and the running time, depend on the (discarded) rejected words.

>>> Just gen <- new "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456"
>>> int_range (-10) 10 gen
5

bytes :: PrimMonad m => Int -> Gen (PrimState m) -> m ByteString Source #

Generate the given number of bytes. Non-positive counts yield the empty string.

>>> import qualified Data.ByteString.Base16 as B16
>>> Just gen <- new "ABCDEFGHIJKLMNOPQRSTUVWXYZ123456"
>>> fmap B16.encode (bytes 8 gen)
"a516463d06b673b7"

Splitting

split :: PrimMonad m => Gen (PrimState m) -> m (Gen (PrimState m)) Source #

Derive a new generator, seeded from the next 32 bytes of output.

The two generators' outputs are independent; use split to give each thread its own generator.

>>> Just gen <- new_system
>>> child <- split gen

Wiping

wipe :: PrimMonad m => Gen (PrimState m) -> m () Source #

Erase a generator's state.

Call this when finished with a generator, to wipe its key and any unused output from memory. The generator must not be used afterwards: it would then produce output from an all-zero key, which is predictable.

>>> Just gen <- new_system
>>> out <- bytes 32 gen
>>> wipe gen