A module for the common task of random number generation.

Random number generators (RNG) are applicable to a wide variety of fields, including cryptography and statistics. They tend to come in two basic varieties: "true" random generators (TRNG) that obtain entropy by measuring some physical random process, and pseudo- random generators (PRNG) that produce long sequences of unpredictable values based on permutations of a much shorter initial key.

Most practical systems take a hybrid approach that involves reseeding a cryptographically secure pseudo-random generator (CSPRNG) periodically from some a source of true entropy, which is the approach that the Botan C++ library takes.

NOTE: Be forewarned that virtual machines usually lack access to a source of true entropy.

This module provides two methods of using the random number generator, which are repeated throughout other modules in the rest of the library, thus affecting their design:

• Directly using an RNG context
• Implicit access to an RNG context using MonadRandomIO

Use of MonadRandomIO is preferred.

Directly using an RNG context

Direct usage is very simple: an RNG context is created, and must be passed around manually.

main = do
    rng <- newRNG Autoseeded
    addEntropyRNG "Fee fi fo fum!" rng
    reseedRNG 32 rng
    x <- getRandomBytesRNG 12 rng
    print x

Implicit access to an RNG context using MonadRandomIO

Monadic usage is very simple: IO is itself a convenient instance of MonadRandomIO that uses the systemRNG:

main = do
    x <- getRandomBytes 12
    print x

The runRandomIO function is used to run a MonadRandomIO action in RandomIO with a specific RNG:

main = do
    rng <- newRNG Autoseeded
    flip runRandomIO rng $ do
        addEntropy "Fee fi fo fum!"
        x <- getRandomBytes 12
        liftIO $ print x

The RandomT transformer and runRandomT functions can also be run with any MonadIO, since RandomIO and RandomT are both instances of MonadRandomIO.

getSomeBytes :: (MonadIO m) => RandomT (ReaderT Int m) ByteString
getSomeBytes = do
    n <- lift ask
    getRandomBytes n