README.md
1# Introduction
2
3This package allows Haskell users to easily acquire entropy for use in critical
4security applications by calling out to either windows crypto api, unix/linux's
5`getrandom` and `/dev/urandom`. Hardware RNGs (currently RDRAND, patches
6welcome) are supported via the `hardwareRNG` function.
7
8## Quick Start
9
10To simply get random bytes use `getEntropy`:
11
12```
13#!/usr/bin/env cabal
14{- cabal:
15 build-depends: base, entropy, bytestring
16-}
17import qualified Data.ByteString as BS
18import System.Entropy
19
20main :: IO ()
21main = 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
27Most x86 systems include a hardware random number generator. These can be
28faster but require more trust in the platform:
29
30```
31import qualified Data.ByteString as B
32import System.Entropy
33
34eitherRNG :: Int -> IO B.ByteString
35eitherRNG sz = maybe (getEntropy sz) pure =<< getHardwareEntropy sz
36
37main :: IO ()
38main = print . B.unpack =<< eitherRNG 32
39```
40
41This package supports Windows, {li,u}nix, QNX, and has preliminary support for HaLVM.
42
43Typically tested on Linux and OSX - testers are as welcome as patches.
44
45[![Build Status](https://travis-ci.org/TomMD/entropy.svg?branch=master)](https://travis-ci.org/TomMD/entropy)
46