Portability | portable |
---|---|
Stability | beta |
Maintainer | Thomas.DuBuisson@gmail.com |
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
- data AsRandomGen a = AsRG a
- class CryptoRandomGen g where
- newGen :: ByteString -> Either GenError g
- genSeedLength :: Tagged g ByteLength
- genBytes :: g -> ByteLength -> Either GenError (ByteString, g)
- genBytesWithEntropy :: g -> ByteLength -> ByteString -> Either GenError (ByteString, g)
- reseed :: g -> ByteString -> Either GenError g
- genInteger :: CryptoRandomGen g => g -> (Integer, Integer) -> Either GenError (Integer, g)
- data GenError
- newGenIO :: CryptoRandomGen g => IO g
Documentation
data AsRandomGen a Source
Any CryptoRandomGen
can be used where the RandomGen
class is needed
simply by wrapping with with the AsRG
constructor. Any failures
(Left results from genBytes or newGen) result
in a pattern match exception. Such failures were simply assumed
not possible by the RandomGen
class, hence there is no non-exception
way to indicate a failure.
AsRG a |
Eq a => Eq (AsRandomGen a) | |
Ord a => Ord (AsRandomGen a) | |
Show a => Show (AsRandomGen a) | |
(SplittableGen g, CryptoRandomGen g) => RandomGen (AsRandomGen g) |
class CryptoRandomGen g whereSource
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
.
newGen :: ByteString -> Either GenError gSource
Instantiate a new random bit generator
genSeedLength :: Tagged g ByteLengthSource
Length of input entropy necessary to instantiate or reseed a generator
genBytes :: g -> ByteLength -> Either GenError (ByteString, g)Source
Obtain random data using a generator
genBytesWithEntropy :: g -> ByteLength -> ByteString -> Either GenError (ByteString, g)Source
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 gSource
reseed the generator
genInteger :: CryptoRandomGen g => g -> (Integer, Integer) -> Either GenError (Integer, g)Source
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).
many generators have these error conditions in common
GenErrorOther String | Misc |
RequestedTooManyBytes | Requested more bytes than a single pass can generate (ex: genBytes g i | i > 2^(2^32)) |
RangeInvalid | When using |
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) |
newGenIO :: CryptoRandomGen g => IO gSource
Use System.Crypto.Random to obtain entropy for newGen
.