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


-- | A random effect using crypto-random
--   
--   Any help (especially documentation) is welcome
@package crypto-random-effect
@version 0.2.0.2


-- | An effect that can generate random bytes.
--   
--   It is essentially a <a>State</a> monad with a given <a>CPRG</a>.
module Crypto.Random.Effect

-- | Type marker to ensure that there is only one RNG.
data RNG

-- | Run the effect using <a>SystemRNG</a>.
runSystemRNG :: SetMember Lift (Lift IO) r => Eff (State SystemRNG :> (Reader EntropyPool :> r)) a -> Eff r a

-- | Run the effect with a given <a>EntropyPool</a>.
runRNGWithPool :: (SetMember Lift (Lift IO) r, Typeable gen, CPRG gen) => EntropyPool -> Eff (State gen :> (Reader EntropyPool :> r)) a -> Eff r a

-- | Run the effect without specifying the <a>CPRG</a>.
--   
--   This is only useful when the type of the <a>CPRG</a> is bound by an
--   explicit type annotation (see <a>runSystemRNG</a> which is
--   <a>runRNG</a> with bound type) or any function within the effect binds
--   it.
runRNG :: (SetMember Lift (Lift IO) r, Typeable gen, CPRG gen) => Eff (State gen :> (Reader EntropyPool :> r)) a -> Eff r a

-- | Wrap an effect that uses the <a>CPRG</a> directly.
withRNG :: (SetMember RNG (State gen) r, Typeable gen) => (gen -> Eff r (a, gen)) -> Eff r a

-- | Wrap an IO action that uses the <a>CPRG</a> directly.
withRNGIO :: (SetMember Lift (Lift IO) r, SetMember RNG (State gen) r, Typeable gen) => (gen -> IO (a, gen)) -> Eff r a

-- | 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.
rngFork :: (SetMember RNG (State gen) r, CPRG gen, Typeable gen) => Eff r gen

-- | Generate a number of bytes using the CPRG.
randomBytes :: (SetMember RNG (State gen) r, CPRG gen, Typeable gen) => Int -> Eff r ByteString

-- | Similar to <a>randomBytes</a> 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.
randomBytesWithEntropy :: (SetMember RNG (State gen) r, CPRG gen, Typeable gen) => Int -> Eff r ByteString

-- | Consume a number of random bytes with a pure function.
--   
--   Note, that this is simply
--   
--   <pre>
--   randomBytes cnt &gt;&gt;= return . f
--   </pre>
withRandomBytes :: (SetMember RNG (State gen) r, CPRG gen, Typeable gen) => Int -> (ByteString -> a) -> Eff r a
createEntropyPool :: SetMember Lift (Lift IO) r => Eff r EntropyPool

-- | Grab a chunk of entropy from the entropy pool.
grabEntropy :: (SetMember Lift (Lift IO) r, Member (Reader EntropyPool) r) => Int -> Eff r SecureMem

-- | Grab a chunk of entropy from the entropy pool.
--   
--   Beware: uses unsafePerformIO under the hood.
unsafeGrabEntropy :: Member (Reader EntropyPool) r => Int -> Eff r SecureMem

-- | Cryptographic Pseudo Random Generator
class CPRG gen

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

-- | Pool of Entropy. contains a self mutating pool of entropy, that is
--   always guarantee to contains data.
data EntropyPool :: *
instance Typeable EntropyPool
instance Typeable SystemRNG
instance SetMember * * RNG (State gen) ((:>) * (State gen) a)