| License | BSD-style |
|---|---|
| Maintainer | Vincent Hanquez <vincent@snarc.org> |
| Stability | experimental |
| Portability | Good |
| Safe Haskell | None |
| Language | Haskell98 |
Crypto.Random.API
Contents
Description
- class CPRG g where
- cprgNeedReseed :: g -> ReseedPolicy
- cprgSupplyEntropy :: ByteString -> g -> g
- cprgGenBytes :: Int -> g -> (ByteString, g)
- data ReseedPolicy
- genRandomBytes :: CPRG g => Int -> g -> (ByteString, g)
- genRandomBytes' :: CPRG g => Int -> g -> ([ByteString], g)
- withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)
- getSystemEntropy :: Int -> IO ByteString
- data SystemRandom
- getSystemRandomGen :: IO SystemRandom
Documentation
class CPRG g where
A class of Cryptographic Secure Random generator.
The main difference with the generic haskell RNG is that it return bytes instead of integer.
It is quite similar to the CryptoRandomGen class in crypto-api except that error are not returned to the user. Instead the user is suppose to handle reseeding by using the NeedReseed and SupplyEntropy methods. For other type of errors, the user is expected to generate bytes with the parameters bounds explicity defined here.
The CPRG need to be able to generate up to 2^20 bytes in one call,
Methods
cprgNeedReseed :: g -> ReseedPolicy
Provide a way to query the CPRG to calculate when new entropy is required to be supplied so the CPRG doesn't repeat output, and break assumptions. This returns the number of bytes before which supply entropy should have been called.
cprgSupplyEntropy :: ByteString -> g -> g
Supply entropy to the CPRG, that can be used now or later to reseed the CPRG. This should be used in conjunction to NeedReseed to know when to supply entropy.
cprgGenBytes :: Int -> g -> (ByteString, g)
Generate bytes using the CPRG and the number specified.
For user of the API, it's recommended to use genRandomBytes instead of this method directly. the CPRG need to be able to supply at minimum 2^20 bytes at a time.
Instances
data ReseedPolicy
This is the reseed policy requested by the CPRG
Constructors
| NeverReseed | there is no need to reseed as either the RG doesn't supports it, it's done automatically or pratically the reseeding period exceed a Word64 type. |
| ReseedInBytes Word64 | the RG need to be reseed in the number of bytes joined to the type. it should be done before the number reached 0, otherwise an user of the RG might request too many bytes and get repeated random bytes. |
Instances
Arguments
| :: CPRG g | |
| => Int | number of bytes to return |
| -> g | CPRG to use |
| -> (ByteString, g) |
Generate bytes using the cprg in parameter.
If the number of bytes requested is really high,
it's preferable to use genRandomBytes for better memory efficiency.
Arguments
| :: CPRG g | |
| => Int | number of bytes to return |
| -> g | CPRG to use |
| -> ([ByteString], g) |
Generate bytes using the cprg in parameter.
This is not tail recursive and an excessive len (>= 2^29) parameter would result in stack overflow.
withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)
this is equivalent to using Control.Arrow first with genRandomBytes.
namely it generate len bytes and map the bytes to the function f
getSystemEntropy :: Int -> IO ByteString
Return system entropy using the entropy package getEntropy
System Random generator
data SystemRandom
This is a simple generator that pull bytes from the system entropy directly. Its randomness and security properties are absolutely depends on the underlaying system implementation.
Instances
getSystemRandomGen :: IO SystemRandom
Get a random number generator based on the standard system entropy source