Crypto.Random

This module is for instantiating cryptographically strong determinitic random bit generators (DRBGs, aka PRNGs) For the simple use case of using the system random number generator (System.Crypto.Random) to seed the DRBG:

   g <- newGenIO

Users needing to provide their own entropy can call newGen directly

    entropy <- getEntropy nrBytes
    let generator = newGen entropy

Documentation

class CryptoRandomGen g where

A class of random bit generators that allows for the possibility of failure, reseeding, providing entropy at the same time as requesting bytes

Minimum complete definition: newGen, genSeedLength, genBytes, reseed.

Methods

newGen :: ByteString -> Either GenError g

Instantiate a new random bit generator

genSeedLength :: Tagged g ByteLength

Length of input entropy necessary to instantiate or reseed a generator

genBytes :: g -> ByteLength -> Either GenError (ByteString, g)

Obtain random data using a generator

genBytesWithEntropy :: g -> ByteLength -> ByteString -> Either GenError (ByteString, g)

genBytesWithEntropy g i entropy generates i random bytes and use the additional input entropy in the generation of the requested data to increase the confidence our generated data is a secure random stream.

Default:

     genBytesWithEntropy g bytes entropy = xor entropy (genBytes g bytes)

reseed :: g -> ByteString -> Either GenError g

reseed the generator

genInteger :: CryptoRandomGen g => g -> (Integer, Integer) -> Either GenError (Integer, g)

genInteger g (low,high) will generate an integer between [low, high] inclusively, swapping the pair if high < low.

This function has degraded (theoretically unbounded, probabilitically decent) performance the closer your range size (high - low) is to 2^n (from the top).

data GenError

many generators have these error conditions in common

Constructors

GenErrorOther String

Misc

RequestedTooManyBytes

Requested more bytes than a single pass can generate (ex: genBytes g i | i > 2^(2^32))

RangeInvalid

When using genInteger g (l,h) and logBase 2 (h - l) > (maxBound :: Int).

NeedReseed

Some generators cease operation after too high a count without a reseed (ex: NIST SP 800-90)

NotEnoughEntropy

For instantiating new generators (or reseeding)

Instances

Eq GenError

Ord GenError

Show GenError

Monad (Either GenError)

newGenIO :: CryptoRandomGen g => IO g

Use System.Crypto.Random to obtain entropy for newGen.