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


-- | 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 GHC.Classes.Eq Crypto.Random.Test.RandomTestResult
instance GHC.Show.Show Crypto.Random.Test.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.
--   
--   Great care need to be taken here when using the output, as this use
--   unsafePerformIO to actually get entropy.
--   
--   Use grabEntropyIO if unsure.
grabEntropy :: Int -> EntropyPool -> SecureMem

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

-- | Cryptographic Pseudo Random Generator
class CPRG gen

-- | Create a new CPRG using an object of the CryptoGenerator class and
--   with an explicit reference to an EntropyPool.
cprgCreate :: CPRG gen => EntropyPool -> gen

-- | Give the ability to set a threshold of byte generated that after being
--   exceeded will result in a reseed with some stateful entropy after a
--   call to <a>cprgGenerate</a>
--   
--   If this threshold is exceeded during the set operation, the rng should
--   be reseeded here.
--   
--   If this value is set to 0, no reseeding will be done and the output
--   will be completely predicable. This is not a recommended level except
--   for debugging and testing purpose.
cprgSetReseedThreshold :: CPRG gen => Int -> gen -> gen

-- | Fork a CPRG into a new independent CPRG.
--   
--   As entropy is mixed to generate safely a new generator, 2 calls with
--   the same CPRG will not produce the same output.
cprgFork :: CPRG gen => gen -> (gen, gen)

-- | Generate a number of bytes using the CPRG.
--   
--   Given one CPRG, the generated bytes will always be the same.
--   
--   However the returned CPRG might have been reseeded with entropy bits,
--   so 2 calls with the same CPRG will not necessarily result in the same
--   next CPRG.
cprgGenerate :: CPRG gen => Int -> gen -> (ByteString, gen)

-- | Similar to cprgGenerate except that the random data is mixed with pure
--   entropy, so the result is not reproducible after use, but it provides
--   more guarantee, theorically speaking, in term of the randomness
--   generated.
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 Crypto.Random.Generator.CPRG Crypto.Random.SystemRNG


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

-- | Cryptographic Pseudo Random Generator
class CPRG gen

-- | Create a new CPRG using an object of the CryptoGenerator class and
--   with an explicit reference to an EntropyPool.
cprgCreate :: CPRG gen => EntropyPool -> gen

-- | Give the ability to set a threshold of byte generated that after being
--   exceeded will result in a reseed with some stateful entropy after a
--   call to <a>cprgGenerate</a>
--   
--   If this threshold is exceeded during the set operation, the rng should
--   be reseeded here.
--   
--   If this value is set to 0, no reseeding will be done and the output
--   will be completely predicable. This is not a recommended level except
--   for debugging and testing purpose.
cprgSetReseedThreshold :: CPRG gen => Int -> gen -> gen

-- | Fork a CPRG into a new independent CPRG.
--   
--   As entropy is mixed to generate safely a new generator, 2 calls with
--   the same CPRG will not produce the same output.
cprgFork :: CPRG gen => gen -> (gen, gen)

-- | Generate a number of bytes using the CPRG.
--   
--   Given one CPRG, the generated bytes will always be the same.
--   
--   However the returned CPRG might have been reseeded with entropy bits,
--   so 2 calls with the same CPRG will not necessarily result in the same
--   next CPRG.
cprgGenerate :: CPRG gen => Int -> gen -> (ByteString, gen)

-- | Similar to cprgGenerate except that the random data is mixed with pure
--   entropy, so the result is not reproducible after use, but it provides
--   more guarantee, theorically speaking, in term of the randomness
--   generated.
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)
