raaz-0.3.2: Fast and type safe cryptography.
Copyright(c) Piyush P Kurur 2016
LicenseApache-2.0 OR BSD-3-Clause
MaintainerPiyush P Kurur <ppk@iitpkd.ac.in>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Raaz.Random

Description

 
Synopsis

Cryptographically secure randomness.

This module provides cryptographically secure pseudo-random bytes. The state of the csprg is kept track in the memory element RandomState and should be run using withRandomState.

data RandomState #

Instances

Instances details
WriteAccessible RandomState 
Instance details

Defined in PRGenerator

ByteSource RandomState 
Instance details

Defined in PRGenerator

Methods

fillBytes :: BYTES Int -> RandomState -> Ptr a -> IO (FillResult RandomState)

Memory RandomState 
Instance details

Defined in PRGenerator

withRandomState Source #

Arguments

:: (RandomState -> IO a)

The action that requires csprg state.

-> IO a 

Execute an action that takes the CSPRG state.

randomByteString :: LengthUnit l => l -> RandomState -> IO ByteString Source #

Generate a random byteString.

class Random a where Source #

Elements that can be randomly generated.

Minimal complete definition

Nothing

Methods

random :: RandomState -> IO a Source #

Instances

Instances details
Random Int8 Source # 
Instance details

Defined in Raaz.Random

Random Int16 Source # 
Instance details

Defined in Raaz.Random

Random Int32 Source # 
Instance details

Defined in Raaz.Random

Random Int64 Source # 
Instance details

Defined in Raaz.Random

Random Word8 Source # 
Instance details

Defined in Raaz.Random

Random Word16 Source # 
Instance details

Defined in Raaz.Random

Random Word32 Source # 
Instance details

Defined in Raaz.Random

Random Word64 Source # 
Instance details

Defined in Raaz.Random

Random R Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO R Source #

Random (Key ChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Key ChaCha20) Source #

Random (Key XChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Key XChaCha20) Source #

Storable prim => Random (Key (Keyed prim)) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Key (Keyed prim)) Source #

Random (Nounce ChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Nounce ChaCha20) Source #

Random (Nounce XChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Nounce XChaCha20) Source #

Random w => Random (BE w) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (BE w) Source #

Random w => Random (LE w) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (LE w) Source #

(Random a, Random b) => Random (a, b) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (a, b) Source #

(Dimension d, Unbox w, Random w) => Random (Tuple d w) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (Tuple d w) Source #

(Random a, Random b, Random c) => Random (a, b, c) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (a, b, c) Source #

(Random a, Random b, Random c, Random d) => Random (a, b, c, d) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (a, b, c, d) Source #

(Random a, Random b, Random c, Random d, Random e) => Random (a, b, c, d, e) Source # 
Instance details

Defined in Raaz.Random

Methods

random :: RandomState -> IO (a, b, c, d, e) Source #

Generating sensitive data

Sensitive data like long term asymmetric keys need to be handled with care as they may be inadvertently leaked into permanent storage when memory is swapped out. Most of the time such keys are generated using cryptographically pseudo-random bytes. However, a direct approach, namely using random, to generate them hides a subtle bug. For example the code below is unsafe.

-- WARNING: Not safe from swapping
main     :: withSecureRandomState myAction
myAction ::  MySecretMem -> RandomState -> IO ()
myAction mySecMem rstate = do secret <- random rstate
                                -- the pure value secret is in
                                -- the haskell heap and therefore
                                -- escapes locking
                              initialise secret mysecmem
                              doSomething

The random interface gives a pure Haskell value and is stored in the Haskell heap. Although memory locking is often available on modern operating systems, it is impossible to lock this value as the garbage collector keeps moving values around.

How can we work around this problem ? The intention of the programmer when using the above code was to randomise the contents of the mySecMem memory element. We recommend converting the above code to the following

main = withSecureRandomisedMemory action
myAction ::  MySecretMem -> RandomState -> IO ()
myAction mySecMem rstate = do randomiseMemory mySecMem
                              doSomething

The above code, though correct, is fragile as missing out on the randomiseMemory call can jeopardise the safety of the code. Often the randomisation is required only at the beginning of the task and in this case it is better to use the safer alternative withSecureRandomisedMemory

randomiseMemory :: WriteAccessible mem => mem -> RandomState -> IO () Source #

Randomise the contents of an accessible memory.

withRandomisedMemory Source #

Arguments

:: WriteAccessible mem 
=> (mem -> IO a)

memory action

-> IO a 

Run a memory action which is passed a memory cell whose contents are randomised with cryptographically secure pseudo-random bytes.

withSecureRandomisedMemory Source #

Arguments

:: WriteAccessible mem 
=> (mem -> IO a)

memory action

-> IO a 

Similar to withRandomisedMemory but all memory allocation is locked. Use this when the randomised content is to be protected from swapping.

withSecureRandomState Source #

Arguments

:: Memory mem 
=> (mem -> RandomState -> IO a)

The action that requires random state

-> IO a 

Execute an action that takes a memory element and random state such that all the memory allocated for both of them is locked.

Low level code

fillRandomBytes :: (LengthUnit l, Pointer ptr) => l -> Dest (ptr a) -> RandomState -> IO () #

class Storable a => RandomStorable a where Source #

Subclass of Storable which can be randomly generated. It might appear that all instances of the class Storable should be be instances of this class, after all we know the size of the element, why not write that many random bytes. In fact, this module provides an unsafeFillRandomElements which does that. However, we do not give a blanket definition for all storables because for certain refinements of a given type, like for example, Word8's modulo 10, unsafeFillRandomElements introduces unacceptable skews.

Methods

fillRandomElements Source #

Arguments

:: Int

number of elements to fill

-> Ptr a

The buffer to fill

-> RandomState 
-> IO () 

Fill the buffer with so many random elements of type a.

Instances

Instances details
RandomStorable Int Source # 
Instance details

Defined in Raaz.Random

RandomStorable Int8 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Int16 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Int32 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Int64 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Word Source # 
Instance details

Defined in Raaz.Random

RandomStorable Word8 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Word16 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Word32 Source # 
Instance details

Defined in Raaz.Random

RandomStorable Word64 Source # 
Instance details

Defined in Raaz.Random

RandomStorable R Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr R -> RandomState -> IO () Source #

RandomStorable (Key ChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (Key ChaCha20) -> RandomState -> IO () Source #

RandomStorable (Key XChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (Key XChaCha20) -> RandomState -> IO () Source #

RandomStorable (Nounce ChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (Nounce ChaCha20) -> RandomState -> IO () Source #

RandomStorable (Nounce XChaCha20) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (Nounce XChaCha20) -> RandomState -> IO () Source #

RandomStorable w => RandomStorable (BE w) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (BE w) -> RandomState -> IO () Source #

RandomStorable w => RandomStorable (LE w) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (LE w) -> RandomState -> IO () Source #

(Dimension d, Unbox w, RandomStorable w) => RandomStorable (Tuple d w) Source # 
Instance details

Defined in Raaz.Random

Methods

fillRandomElements :: Int -> Ptr (Tuple d w) -> RandomState -> IO () Source #

fillRandom :: (RandomStorable a, Pointer ptr) => Int -> ptr a -> RandomState -> IO () Source #

Fill the given generalised pointer buffer with random elements.

unsafeFillRandomElements :: Storable a => Int -> Ptr a -> RandomState -> IO () Source #

This is a helper function that has been exported to simplify the definition of a RandomStorable instance for Storable types. However, there is a reason why we do not give a blanket instance for all instances of the Storable class and why this function is unsafe. This function generates a random element of type a by generating n random bytes where n is the size of the elements of a. For instances that range the entire n byte space this is fine. However, if the type is actually a refinement of such a type, (consider a Word8 modulo 10 for example) this function might generate unacceptable skew in the distribution. Hence this function is prefixed unsafe.

Information