crypto-random-0.0.9: Simple cryptographic random related types

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | Good
Safe Haskell | None
Language | Haskell98

Crypto.Random

Contents

- Entropy
- Random generation
- System generator
- Testing and mocking

Description

Provide a safe abstraction for cryptographic pseudo random generator.

Synopsis

- data EntropyPool
- createEntropyPool :: IO EntropyPool
- grabEntropy :: Int -> EntropyPool -> SecureMem
- grabEntropyIO :: Int -> EntropyPool -> IO SecureMem
- class CPRG gen where
- withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g)
- data SystemRNG
- createTestEntropyPool :: ByteString -> EntropyPool

# Entropy

data EntropyPool #

Pool of Entropy. contains a self mutating pool of entropy, that is always guarantee to contains data.

createEntropyPool :: IO EntropyPool #

Create a new entropy pool with a default size.

While you can create as many entropy pool as you want, the pool can be shared between multiples RNGs.

grabEntropy :: Int -> EntropyPool -> SecureMem #

Grab a chunk of entropy from the entropy pool.

Great care need to be taken here when using the output, as this use unsafePerformIO to actually get entropy.

Use grabEntropyIO if unsure.

grabEntropyIO :: Int -> EntropyPool -> IO SecureMem #

Grab a chunk of entropy from the entropy pool.

# Random generation

class CPRG gen where #

Cryptographic Pseudo Random Generator

Minimal complete definition

cprgCreate, cprgSetReseedThreshold, cprgFork, cprgGenerate, cprgGenerateWithEntropy

Methods

cprgCreate :: EntropyPool -> gen #

Create a new CPRG using an object of the CryptoGenerator class and with an explicit reference to an EntropyPool.

cprgSetReseedThreshold :: Int -> gen -> gen #

Give the ability to set a threshold of byte generated that after being exceeded will result in a reseed with some stateful entropy after a call to `cprgGenerate`

If this threshold is exceeded during the set operation, the rng should be reseeded here.

If this value is set to 0, no reseeding will be done and the output will be completely predicable. This is not a recommended level except for debugging and testing purpose.

cprgFork :: gen -> (gen, gen) #

Fork a CPRG into a new independent CPRG.

As entropy is mixed to generate safely a new generator, 2 calls with the same CPRG will not produce the same output.

cprgGenerate :: Int -> gen -> (ByteString, gen) #

Generate a number of bytes using the CPRG.

Given one CPRG, the generated bytes will always be the same.

However the returned CPRG might have been reseeded with entropy bits, so 2 calls with the same CPRG will not necessarily result in the same next CPRG.

cprgGenerateWithEntropy :: Int -> gen -> (ByteString, gen) #

Similar to cprgGenerate except that the random data is mixed with pure entropy, so the result is not reproducible after use, but it provides more guarantee, theorically speaking, in term of the randomness generated.

Instances

CPRG SystemRNG # |
Methods cprgCreate :: EntropyPool -> SystemRNG # cprgSetReseedThreshold :: Int -> SystemRNG -> SystemRNG # cprgFork :: SystemRNG -> (SystemRNG, SystemRNG) # cprgGenerate :: Int -> SystemRNG -> (ByteString, SystemRNG) # cprgGenerateWithEntropy :: Int -> SystemRNG -> (ByteString, SystemRNG) #

withRandomBytes :: CPRG g => g -> Int -> (ByteString -> a) -> (a, g) #

generate `len random bytes and mapped the bytes to the function` f.

This is equivalent to use Control.Arrow `first` with `cprgGenerate`

# System generator

data SystemRNG #

System entropy generator.

This generator doesn't use the entropy reseed level, as the only bytes generated are comping from the entropy pool already.

This generator doesn't create reproducible output, and might be difficult to use for testing and debugging purpose, but otherwise for real world use case should be fine.

Instances

CPRG SystemRNG # |
Methods cprgCreate :: EntropyPool -> SystemRNG # cprgSetReseedThreshold :: Int -> SystemRNG -> SystemRNG # cprgFork :: SystemRNG -> (SystemRNG, SystemRNG) # cprgGenerate :: Int -> SystemRNG -> (ByteString, SystemRNG) # cprgGenerateWithEntropy :: Int -> SystemRNG -> (ByteString, SystemRNG) #

# Testing and mocking

createTestEntropyPool :: ByteString -> EntropyPool #

Create a dummy entropy pool that is deterministic, and dependant on the input bytestring only.

This is stricly reserved for testing purpose when a deterministic seed need to be generated with deterministic RNGs.

Do not use in production code.