@@ -5,17 +5,37 @@ security applications by calling out to either windows crypto api, unix/linux's
55`/dev/urandom`. Hardware RNGs (currently RDRAND, patches welcome) are supported
66via the `hardwareRNG` function.
77
8−If you wish to obtain an XOR of the hardware and system RNG consider:
8+## Quick Start
9+
10+To simply get random bytes use `getEntropy`:
11+
12+```
13+#!/usr/bin/env cabal
14+{- cabal:
15+ build-depends: base, entropy, bytestring
16+-}
17+import qualified Data.ByteString as BS
18+import System.Entropy
19+
20+main :: IO ()
21+main = print . BS.unpack =<< getEntropy 16
22+-- Example output: [241,191,215,193,225,27,121,244,16,155,252,41,131,38,6,100]
23+```
24+
25+## Faster Randoms from Hardware
26+
27+Most x86 systems include a hardware random number generator. These can be
28+faster but require more trust in the platform:
929
1030```
11−import Data.Bits (xor)
1231import qualified Data.ByteString as B
13−import qualified Control.Exception as X
32+import System.Entropy
33+
34+eitherRNG :: Int -> IO B.ByteString
35+eitherRNG sz = maybe (getEntropy sz) pure =<< getHardwareEntropy sz
1436
15−xorRNG sz = do hw <- hardwareRNG sz
16− h <- openHandle
17− sys <- hGetEntropy h `X.finally` closeHandle h
18− pure $ B.pack $ B.zipWith xor hw sys
37+main :: IO ()
38+main = print . B.unpack =<< eitherRNG 32
1939```
2040
2141This package supports Windows, {li,u}nix, QNX, and has preliminary support for HaLVM.