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.

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