System.Entropy

entropy-0.4.1.11: A platform independent entropy source

Maintainer | Thomas.DuBuisson@gmail.com
Stability | beta
Portability | portable
Safe Haskell | None
Language | Haskell2010

System.Entropy

Description

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.

Synopsis

- getEntropy :: Int -> IO ByteString
- getHardwareEntropy :: Int -> IO (Maybe ByteString)
- data CryptHandle
- openHandle :: IO CryptHandle
- hGetEntropy :: CryptHandle -> Int -> IO ByteString
- closeHandle :: CryptHandle -> IO ()

# Documentation

getEntropy #

Arguments

:: Int | Number of bytes
-> IO ByteString |

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.

getHardwareEntropy #

Arguments

:: Int | Number of bytes
-> IO (Maybe 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.

data CryptHandle #

Handle for manual resource management

openHandle :: IO CryptHandle #

Open a `CryptHandle`

hGetEntropy :: CryptHandle -> Int -> IO ByteString #

Read random data from a `CryptHandle`

closeHandle :: CryptHandle -> IO () #

Close the `CryptHandle`