Portability | portable |
---|---|

Stability | beta |

Maintainer | Thomas.DuBuisson@gmail.com |

This module is the convenience interface for the DRBG (NIST standardized
number-theoretically secure random number generator). Everything is setup
for using the crypto-api `CryptoRandomGen`

type class. For example,
to seed a new generator with the system secure random (`System.Crypto.Random`

)
and generate some bytes (stepping the generator along the way) one would do:

gen <- newGenIO :: IO HashDRBG let Right (randomBytes, newGen) = genBytes 1024 gen

Selecting the underlying hash algorithm is supporting using *DRBGWith types:

gen <- newGenIO :: IO (HmacDRBGWith SHA224)

Composition of generators is supported using two trivial compositions, `GenXor`

and `GenAutoReseed`

. Additional compositions can be built by instanciating
a `CryptoRandomGen`

as desired.

gen <- newGenIO :: IO (GenBuffered (GenAutoReseed (GenXor AesCntDRBG (HashDRBGWith SHA384)) HmacDRBG))

- type HmacDRBG = State SHA512
- type HashDRBG = State SHA512
- type HmacDRBGWith = State
- type HashDRBGWith = State
- data GenXor a b
- data GenAutoReseed a b
- data GenBuffered g
- module Crypto.Random

# Documentation

type HmacDRBGWith = StateSource

The HMAC DRBG state (of kind * -> *) allowing selection of the underlying hash algorithm (SHA1, SHA224 ... SHA512)

type HashDRBGWith = StateSource

The Hash DRBG state (of kind * -> *) allowing selection of the underlying hash algorithm.

`g :: GenXor a b`

generates bytes with sub-generators a and b
and exclusive-or's the outputs to produce the resulting bytes.

(CryptoRandomGen a, CryptoRandomGen b) => CryptoRandomGen (GenXor a b) |

data GenAutoReseed a b Source

`g :: GenAutoReseed a b`

is a generator of type a that gets
automatically reseeded by generator b upon every 32kB generated.

`reseed g ent`

will reseed both the component generators by
breaking ent up into two parts determined by the genSeedLength of each generator.

`genBytes`

will generate the requested bytes with generator `a`

and reseed `a`

using generator `b`

if there has been 32KB of generated data since the last reseed.
Note a request for > 32KB of data will be filled in one request to generator `a`

before
`a`

is reseeded by `b`

.

`genBytesWithEntropy`

will push the entropy into generator `a`

, leaving generator
`b`

unchanged unless the count hits 32KB, in which case it is reseeds `a`

(for a second time) using `b`

as in normal operation via `genBytes`

.

(CryptoRandomGen a, CryptoRandomGen b) => CryptoRandomGen (GenAutoReseed a b) |

data GenBuffered g Source

`g :: GenBuffered a`

is a generator of type `a`

that attempts to
maintain a buffer of random values size >= 1MB and <= 5MB at any time.

CryptoRandomGen g => CryptoRandomGen (GenBuffered g) |

module Crypto.Random