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

-- | A platform independent entropy source
--   
--   A mostly platform independent method to obtain cryptographically
--   strong entropy (RDRAND, urandom, CryptAPI, and patches welcome) Users
--   looking for cryptographically strong (number-theoretically sound)
--   PRNGs should see the DRBG package too.
@package entropy
@version 0.4.1.11

-- | Obtain entropy from system sources or x86 RDRAND when available.
--   
--   Currently supporting:
--   
--   
--   
- Windows via CryptoAPI
--   
- *nix systems via /dev/urandom
--   
- Includes QNX
--   
- ghcjs/browser via JavaScript crypto API.
--   
module System.Entropy

-- | Get a specific number of bytes of cryptographically secure random data
--   using the *system-specific* sources. (As of 0.4. Versions <0.4
--   mixed system and hardware sources)
--   
--   The returned random value is considered cryptographically secure but
--   not true entropy.
--   
--   On some platforms this requires a file handle which can lead to
--   resource exhaustion in some situations.
getEntropy :: Int -> IO ByteString

-- | Get a specific number of bytes of cryptographically secure random data
--   using a supported *hardware* random bit generator.
--   
--   If there is no hardware random number generator then Nothing
--   is returned. If any call returns non-Nothing then it should never be
--   Nothing unless there has been a hardware failure.
--   
--   If trust of the CPU allows it and no context switching is important, a
--   bias to the hardware rng with system rng as fall back is trivial:
--   
--   
--   let fastRandom nr = maybe (getEntropy nr) pure =<< getHardwareEntropy nr
--   
--   
--   The old, <0.4, behavior is possible using xor
--   from Bits:
--   
--   
--   let oldRandom nr =
--        do hwRnd  maybe (replicate nr 0) BS.unpack <$ getHardwareEntropy nr
--           sysRnd BS.unpack <$ getEntropy nr
--           pure $ BS.pack $ zipWith xor sysRnd hwRnd
--   
--   
--   A less maliable mixing can be accomplished by replacing xor
--   with a composition of concat and cryptographic hash.
getHardwareEntropy :: Int -> IO (Maybe ByteString)

-- | Handle for manual resource management
data CryptHandle

-- | Open a CryptHandle
openHandle :: IO CryptHandle

-- | Read random data from a CryptHandle
hGetEntropy :: CryptHandle -> Int -> IO ByteString

-- | Close the CryptHandle
closeHandle :: CryptHandle -> IO ()
