-- 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

-- | 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.
cprgNeedReseed :: CPRG g => g -> ReseedPolicy

-- | 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.
cprgSupplyEntropy :: CPRG g => ByteString -> g -> 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.
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 GHC.Classes.Eq Crypto.Random.API.ReseedPolicy
instance GHC.Show.Show Crypto.Random.API.ReseedPolicy
instance Crypto.Random.API.CPRG Crypto.Random.API.SystemRandom
