Raaz.Core.Transfer.Unsafe

Transfer actions.

Low level buffer operations are problematic portions of any crypto-library. Buffers are usually represented by the starting pointer and one needs to keep track of the buffer sizes carefully. An operation that writes into a buffer, if it writes beyond the actual size of the buffer, can lead to a possible remote code execution. On the other hand, when reading from a buffer, if we read beyond the buffer it can leak private data to the attacker (as in the case of Heart bleed bug). This module is indented to give a relatively high level interface to this problem. We expose two types, the ReadM and the Write type which deals with these two aspects. Both these actions keep track of the number of bytes that they transfer.

type Transfer t = SemiR (TransferAction t) (BYTES Int)

An element of type `Tranfer t m` is an action which when executed transfers bytes into or out of its input buffer. The type Transfer t m forms a monoid and hence can be concatenated using the <> operator.

type ReadFrom = Transfer 'ReadFromBuffer

The ReadFrom is the type that captures the act of reading from a buffer and possibly doing some action on the bytes read. Although inaccurate, it is helpful to think of elements of ReadFromM as action that on an input buffer transfers data from it to some unspecified source.

ReadFrom actions form a monoid with the following semantics: if r1 and r2 are two read actions then r1 <> r2 first reads the the data associated with r1 and then reads the data associated with r2.

type WriteTo = Transfer 'WriteToBuffer

The Write is the type that captures the act of writing to a buffer. Although inaccurate, it is helpful to think of elements of Write as source of bytes of a fixed size.

Write actions form a monoid with the following semantics: if w1 and w2 are two write actions then w1 <> w2 first writes the data associated from w1 and then the writes the data associated with w2.

unsafeMakeTransfer

Arguments

:: LengthUnit u

=> u

length of pointer accessed

-> (Ptr Word8 -> IO ())

Pointer action to run

-> Transfer t

Make an explicit transfer action.

unsafeTransfer

Arguments

:: Pointer ptr

=> Transfer t

-> ptr a

The pointer to the buffer to/from which transfer occurs.

-> IO ()

Perform the transfer without checking the bounds.

unsafeInterleave

Arguments

:: IO a

-> Transfer t

This combinator runs an IO action which does not read/write any bytes form the input buffer. This can be used to interleave some side action in between the transfer.

unsafeReadIntoPtr

Arguments

:: (Pointer ptr, LengthUnit sz)

=> sz

how much to read.

-> Dest (ptr Word8)

buffer to read the bytes into

-> ReadFrom

The action unsafeReadIntoPtr sz dptr gives a read action, which if run on an input buffer, will transfers sz bytes to the destination pointer dptr. This action is unsafe because no checks are done (or is it possible) to see if the destination pointer has enough space to accommodate the bytes read.

unsafeReadInto

Arguments

:: EndianStore a

=> Int

how many elements to read.

-> Dest (Ptr a)

buffer to read the elements into

-> ReadFrom

The action unsafeReadInto n dptr gives a read action which if run on an input buffer, will transfers n elements of type a into the buffer pointed by dptr. Like unsafeReadIntoPtr this function does no checks on the destination pointer and hence is unsafe.

unsafeWriteFrom :: EndianStore a => Int -> Src (Ptr a) -> WriteTo

Write many elements from the given buffer

unsafeWriteFromPtr :: (Pointer ptr, LengthUnit sz) => sz -> Src (ptr Word8) -> WriteTo

The action writeFromPtr sz sptr gives a write action, which if run on an input buffer buf, will transfers sz bytes from the source pointer sptr to the given buffer. Note that it is the responsibility of the user to make sure that the input buffer buf has enough space to receive sz units of data if and when the read action is executed.

writeByteString :: ByteString -> WriteTo

Writes a strict bytestring.

transferSize :: Transfer t -> BYTES Int

Returns the bytes that will be written when the write action is performed.