-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Simple random generators API for cryptography related code
--   
--   Simple random generators API for cryptography related code
@package crypto-random-api
@version 0.2.0


module Crypto.Random.API

-- | 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,
class CPRG g
cprgNeedReseed :: CPRG g => g -> ReseedPolicy
cprgSupplyEntropy :: CPRG g => ByteString -> g -> g
cprgGenBytes :: CPRG g => Int -> g -> (ByteString, g)

-- | This is the reseed policy requested by the CPRG
data ReseedPolicy

-- | 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.
NeverReseed :: ReseedPolicy

-- | 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.
ReseedInBytes :: Word64 -> ReseedPolicy

-- | Generate bytes using the cprg in parameter.
--   
--   If the number of bytes requested is really high, it's preferable to
--   use <a>genRandomBytes</a> for better memory efficiency.
genRandomBytes :: CPRG g => Int -> g -> (ByteString, g)

-- | Generate bytes using the cprg in parameter.
--   
--   This is not tail recursive and an excessive len (&gt;= 2^29) parameter
--   would result in stack overflow.
genRandomBytes' :: CPRG g => Int -> g -> ([ByteString], g)

-- | this is equivalent to using Control.Arrow <tt>first</tt> with
--   <a>genRandomBytes</a>.
--   
--   namely it generate <tt>len bytes and map the bytes to the function
--   </tt>f
withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)

-- | Return system entropy using the entropy package <tt>getEntropy</tt>
getSystemEntropy :: Int -> IO ByteString

-- | 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.
data SystemRandom

-- | Get a random number generator based on the standard system entropy
--   source
getSystemRandomGen :: IO SystemRandom
instance Show ReseedPolicy
instance Eq ReseedPolicy
instance CPRG SystemRandom