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


-- | A platform independent entropy source
--   
--   A 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 <a>DRBG</a> package too.
@package entropy
@version 0.4


-- | Obtain entropy from system sources or x86 RDRAND when available.
--   
--   Currently supporting:
--   
--   <ul>
--   <li>Windows via CryptoAPI</li>
--   <li>*nix systems via <tt>/dev/urandom</tt></li>
--   <li>Includes QNX</li>
--   <li>Xen (only when RDRAND is available)</li>
--   </ul>
module System.Entropy

-- | Get a specific number of bytes of cryptographically secure random data
--   using the *system-specific* sources. (As of 0.4. Verions &lt;0.4 mixed
--   system and hardware sources)
--   
--   The returned random value is considered cryptographically secure but
--   not true entropy.
--   
--   On some platforms this requies 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 <tt>Nothing</tt>
--   is returned. If any call returns non-Nothing then it should never be
--   <tt>Nothing</tt> 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:
--   
--   <pre>
--   let fastRandom nr = maybe (getEntropy nr) pure =&lt;&lt; getHardwareEntropy nr
--   </pre>
--   
--   The old, <tt>&lt;0.4</tt>, behavior is possible using <tt>xor</tt>
--   from <a>Bits</a>:
--   
--   <pre>
--   let oldRandom nr =
--        do hwRnd  <a>maybe (replicate nr 0) BS.unpack &lt;$</a> getHardwareEntropy nr
--           sysRnd <a>BS.unpack &lt;$</a> getEntropy nr
--           pure $ BS.pack $ zipWith xor sysRnd hwRnd
--   </pre>
--   
--   A less maliable mixing can be accomplished by replacing <tt>xor</tt>
--   with a composition of concat and cryptographic hash.
getHardwareEntropy :: Int -> IO (Maybe ByteString)

-- | Handle for manual resource management
data CryptHandle

-- | Open a <a>CryptHandle</a>
openHandle :: IO CryptHandle

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

-- | Close the <a>CryptHandle</a>
closeHandle :: CryptHandle -> IO ()