The Memory subsystem.

Any cryptographic primitives use memory to store stuff. This class abstracts all types that hold some memory. Cryptographic application often requires securing the memory from being swapped out (think of memory used to store private keys or passwords). This abstraction supports memory securing. If your platform supports memory locking, then securing a memory will prevent the memory from being swapped to the disk. Once secured the memory location is overwritten by nonsense before being freed.

While some basic memory elements like MemoryCell are exposed from the library, often we require compound memory objects built out of simpler ones. The Applicative instance of the Alloc can be made use of in such situation to simplify such instance declaration as illustrated in the instance declaration for a pair of memory elements.

instance (Memory ma, Memory mb) => Memory (ma, mb) where

   memoryAlloc             = (,) <$> memoryAlloc <*> memoryAlloc

   unsafeToPointer (ma, _) =  unsafeToPointer ma

A memory element that holds nothing.

Copy data from a given memory location to the other. The first argument is destionation and the second argument is source to match with the convention followed in memcpy.

Memories that can be initialised with a pure value. The pure value resides in the Haskell heap and hence can potentially be swapped. Therefore, this class should be avoided if compromising the initialisation value can be dangerous. Consider using InitialiseableFromBuffer

Memories from which pure values can be extracted. Once a pure value is extracted,

A memory type that can be initialised from a pointer buffer. The initialisation performs a direct copy from the input buffer and hence the chances of the initialisation value ending up in the swap is minimised.

A memory type that can extract bytes into a buffer. The extraction will perform a direct copy and hence the chances of the extracted value ending up in the swap space is minimised.

A memory location to store a value of type having Storable instance.

Work with the underlying pointer of the memory cell. Useful while working with ffi functions.

Get the pointer associated with the given memory cell.

A class that captures abstract "memory threads". A memory thread can either be run securely or insecurely. Pure IO actions can be run inside a memory thread using the runIO. However, the IO action that is being run must not directly or indirectly run a secure action ever. In particular, the following code is bad.

-- BAD EXAMPLE: DO NOT USE.
runIO $ securely $ foo

On the other hand the following code is fine

runIO $ insecurely $ someMemoryAction

As to why this is dangerous, it has got to do with the fact that mlock and munlock do not nest correctly. A single munlock can unlock multiple calls of mlock on the same page. Whether a given IO action unlocks memory is difficult to keep track of; for all you know, it might be a FFI call that does an memunlock. Hence, currently there is no easy way to enforce this.

Perform an IO action inside the memory thread.

Get the underlying memory element of the memory thread.

Apply the given function to the value in the cell. For a function f :: b -> a, the action modify f first extracts a value of type b from the memory element, applies f to it and puts the result back into the memory.

modify f = do b          <- extract
              initialise $  f b

Run a given memory action in the memory thread.

An action of type MT mem a is an action that uses internally a single memory object of type mem and returns a result of type a. All the actions are performed on a single memory element and hence the side effects persist. It is analogues to the ST monad.

An IO allocator can be lifted to the memory thread level as follows.

A memory allocator for the memory type mem. The Applicative instance of Alloc can be used to build allocations for complicated memory elements from simpler ones.

Allocates a buffer of size l and returns the pointer to it pointer.