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


-- | Simple cryptographic random related types
--   
--   Simple cryptographic random related types
@package crypto-random
@version 0.0.4


-- | Provide way to test usual simple statisticals test for randomness
module Crypto.Random.Test

-- | Mutable random test State
data RandomTestState

-- | Randomness various result relative to random bytes
data RandomTestResult
RandomTestResult :: Word64 -> Double -> Double -> Double -> Double -> [Double] -> RandomTestResult

-- | Total number of characters
res_totalChars :: RandomTestResult -> Word64

-- | Entropy per byte
res_entropy :: RandomTestResult -> Double

-- | Chi Square
res_chi_square :: RandomTestResult -> Double

-- | Arithmetic Mean
res_mean :: RandomTestResult -> Double

-- | Theorical Compression percent
res_compressionPercent :: RandomTestResult -> Double

-- | Probability of every bucket
res_probs :: RandomTestResult -> [Double]

-- | Initialize new state to run tests
randomTestInitialize :: IO RandomTestState

-- | Append random data to the test state
randomTestAppend :: RandomTestState -> ByteString -> IO ()

-- | Finalize random test state into some result
randomTestFinalize :: RandomTestState -> IO RandomTestResult
instance Show RandomTestResult
instance Eq RandomTestResult


-- | Provide a safe abstraction for cryptographic pseudo random generator.
module Crypto.Random

-- | Pool of Entropy. contains a self mutating pool of entropy, that is
--   always guarantee to contains data.
data EntropyPool

-- | Create a new entropy pool with a default size.
--   
--   While you can create as many entropy pool as you want, the pool can be
--   shared between multiples RNGs.
createEntropyPool :: IO EntropyPool

-- | Grab a chunk of entropy from the entropy pool.
grabEntropy :: Int -> EntropyPool -> SecureMem

-- | Cryptographic Pseudo Random Generator
class CPRG gen
cprgCreate :: CPRG gen => EntropyPool -> gen
cprgSetReseedThreshold :: CPRG gen => Int -> gen -> gen
cprgFork :: CPRG gen => gen -> (gen, gen)
cprgGenerate :: CPRG gen => Int -> gen -> (ByteString, gen)
cprgGenerateWithEntropy :: CPRG gen => Int -> gen -> (ByteString, gen)

-- | generate <tt>len random bytes and mapped the bytes to the function
--   </tt>f.
--   
--   This is equivalent to use Control.Arrow <tt>first</tt> with
--   <a>cprgGenerate</a>
withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)

-- | System entropy generator.
--   
--   This generator doesn't use the entropy reseed level, as the only bytes
--   generated are comping from the entropy pool already.
--   
--   This generator doesn't create reproducible output, and might be
--   difficult to use for testing and debugging purpose, but otherwise for
--   real world use case should be fine.
data SystemRNG

-- | Create a dummy entropy pool that is deterministic, and dependant on
--   the input bytestring only.
--   
--   This is stricly reserved for testing purpose when a deterministic seed
--   need to be generated with deterministic RNGs.
--   
--   Do not use in production code.
createTestEntropyPool :: ByteString -> EntropyPool
instance CPRG SystemRNG


-- | Deprecated interface for compatibility of crypto-random-api user with
--   crypto-random
module Crypto.Random.API

-- | Cryptographic Pseudo Random Generator
class CPRG gen
cprgCreate :: CPRG gen => EntropyPool -> gen
cprgSetReseedThreshold :: CPRG gen => Int -> gen -> gen
cprgFork :: CPRG gen => gen -> (gen, gen)
cprgGenerate :: CPRG gen => Int -> gen -> (ByteString, gen)
cprgGenerateWithEntropy :: CPRG gen => Int -> gen -> (ByteString, gen)

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

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

-- | <i>Deprecated: use cprgGenerate from Crypto.Random instead </i>
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)

-- | generate <tt>len random bytes and mapped the bytes to the function
--   </tt>f.
--   
--   This is equivalent to use Control.Arrow <tt>first</tt> with
--   <a>cprgGenerate</a>
withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)