| crypto-api-0.2.1: A generic interface for cryptographic operations | Contents | Index
Crypto.Random |
Portability | portable
Stability | beta
Maintainer | Thomas.DuBuisson@gmail.com
Description
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
Synopsis
class CryptoRandomGen g where
newGen :: ByteString -> Either GenError g
genSeedLength :: Tagged g ByteLength
genBytes :: ByteLength -> g -> Either GenError (ByteString, g)
genBytesWithEntropy :: ByteLength -> ByteString -> g -> Either GenError (ByteString, g)
reseed :: ByteString -> g -> Either GenError g
data GenError
= GenErrorOther String
| RequestedTooManyBytes
| RangeInvalid
| NeedReseed
| NotEnoughEntropy
newGenIO :: CryptoRandomGen g => IO g
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. The provided bytestring should be of length >= genSeedLength. If the bytestring is shorter then the call may fail (suggested error: `NotEnoughEntropy`). If the bytestring is of sufficent length the call should always succeed.
genSeedLength :: Tagged g ByteLength
Length of input entropy necessary to instantiate or reseed a generator
genBytes :: ByteLength -> g -> Either GenError (ByteString, g)
`genBytes len g` generates a random ByteString of length `len` and new generator. The MonadCryptoRandom package has routines useful for converting the ByteString to commonly needed values (but cereal or other deserialization libraries would also work). This routine can fail if the generator has gone too long without a reseed (usually this is in the ball-park of 2^48 requests). Suggested error in this cases is `NeedReseed`
genBytesWithEntropy :: ByteLength -> ByteString -> g -> 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. Some generators use `entropy` to perturb the state of the generator, meaning:
         (_,g2') <- genBytesWithEntropy len g1 ent
         (_,g2 ) <- genBytes len g1
         g2 /= g2'
But this is not required. Default:
         genBytesWithEntropy g bytes entropy = xor entropy (genBytes g bytes)
reseed :: ByteString -> g -> Either GenError g
If the generator has produced too many random bytes on its existing seed it will throw `NeedReseed`. In that case, reseed the generator using this function and a new high-entropy seed of length >= `genSeedLength`. Using bytestrings that are too short can result in an error (`NotEnoughEntropy`).
data GenError
many generators have these error conditions in common
Constructors
GenErrorOther String | Misc
RequestedTooManyBytes | Requested more bytes than a single pass can generate (The maximum request is generator dependent)
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 |
newGenIO :: CryptoRandomGen g => IO g
Use System.Crypto.Random to obtain entropy for `newGen`.
Produced by Haddock version 2.7.2