A typesafe length for Bytestring

A type safe version of replicate

The action create l act creates a length l bytestring where the contents are filled using the the act to fill the buffer.

The IO action createFrom n cptr creates a bytestring by copying n bytes from the pointer cptr.

Works directly on the pointer associated with the ByteString. This function should only read and not modify the contents of the pointer.

Copy the bytestring to the crypto buffer. This operation leads to undefined behaviour if the crypto pointer points to an area smaller than the size of the byte string.

Similar to unsafeCopyToPointer but takes an additional input n which is the number of bytes (expressed in type safe length units) to transfer. This operation leads to undefined behaviour if either the bytestring is shorter than n or the crypto pointer points to an area smaller than n.

Cryptographic primitives that process bulk data (like ciphers, cryptographic hashes) process data in blocks. For data that is not a multiple of the block size they may have some padding strategy. The type class that captures an abstract block cryptographic primitive.

The type family that captures the key of a keyed primitive.

In addition to keys, certain primitives require nounces that can be public but needs to be distinct across different uses when sharing the key. The type family that captures the nounce for a primitive (if it requires one).

A block of the primitive.

Pointer to a block of the primitive.

Aligned version of block pointers.

Type safe message length in units of blocks of the primitive. When dealing with buffer lengths for a primitive, it is often better to use the type safe units BlockCount. Functions in the raaz package that take lengths usually allow any type safe length as long as they can be converted to bytes. This can avoid a lot of tedious and error prone length calculations.

The expression n blocksOf primProxy specifies the message lengths in units of the block length of the primitive whose proxy is primProxy. This expression is sometimes required to make the type checker happy.

Typical size of L1 cache. Used for selecting buffer size etc in crypto operations.

Abstract byte sources. A bytesource is something that you can use to fill a buffer.

WARNING: The source is required to return Exhausted in the boundary case where it has exactly the number of bytes requested. In other words, if the source returns Remaining on any particular request, there should be at least 1 additional byte left on the source for the next request. Cryptographic block primitives perform certain special processing, like padding for example, for the last block and it is required to know whether the last block has been read or not.

A byte source src is pure if filling from it does not have any other side effect on the state of the byte source. Formally, two different fills form the same source should fill the buffer with the same bytes. This additional constraint on the source helps to purify certain crypto computations like computing the hash or mac of the source. Usualy sources like ByteString etc are pure byte sources. A file handle is a byte source that is not a pure source.

This type captures the result of a fill operation.

A version of fillBytes that takes type safe lengths as input.

Process data from a source in chunks of a particular size.

Combinator to handle a fill result.

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

This class captures memories that can be initialised by writing bytes to (portions of) its buffer.

This class captures memories from which bytes can be extracted directly from (portions of) its buffer.

Data type that gives an access buffer to portion of the memory.

Memories from which pure values can be extracted. Much like the case of the Initialisable class, avoid using this interface if you do not want the data extracted to be swapped. Use the ReadAccessible class instead.

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. Look into the type class WriteAccessible instead.

A memory element that holds nothing.

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 allocator for the memory type mem. The Applicative instance of Alloc can be used to build allocations for complicated memory elements from simpler ones and takes care of handling the size/offset calculations involved.

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

Apply some low level action on the underlying buffer of the memory.

Perform an action which makes use of this memory. The memory allocated will automatically be freed when the action finishes either gracefully or with some exception. Besides being safer, this method might be more efficient as the memory might be allocated from the stack directly and will have very little GC overhead.

Similar to withMemory but allocates a secure memory for the action. Secure memories are never swapped on to disk and will be wiped clean of sensitive data after use. However, be careful when using this function in a child thread. Due to the daemonic nature of Haskell threads, if the main thread exists before the child thread is done with its job, sensitive data can leak. This is essentially a limitation of the bracket which is used internally.

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.

modifyMem f mem = do b <- extract mem
                     initialise (f b) mem

Transfer the bytes from the source memory to the destination memory. The total bytes transferred is the minimum of the bytes available at the source and the space available at the destination.

The location where the actual storing of element happens. This pointer is guaranteed to be aligned to the alignment restriction of a

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

Copy the contents of one memory cell to another.