Copyright | (c) Piyush P Kurur 2019 |
---|---|
License | Apache-2.0 OR BSD-3-Clause |
Maintainer | Piyush P Kurur <ppk@iitpkd.ac.in> |
Stability | experimental |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Synopsis
- type Transfer t = SemiR (TransferAction t) (BYTES Int)
- type ReadFrom = Transfer 'ReadFromBuffer
- type WriteTo = Transfer 'WriteToBuffer
- unsafeMakeTransfer :: LengthUnit u => u -> (Ptr Word8 -> IO ()) -> Transfer t
- unsafeTransfer :: Pointer ptr => Transfer t -> ptr a -> IO ()
- unsafeInterleave :: IO a -> Transfer t
- unsafeReadIntoPtr :: (Pointer ptr, LengthUnit sz) => sz -> Dest (ptr Word8) -> ReadFrom
- unsafeReadInto :: EndianStore a => Int -> Dest (Ptr a) -> ReadFrom
- unsafeWriteFrom :: EndianStore a => Int -> Src (Ptr a) -> WriteTo
- unsafeWriteFromPtr :: (Pointer ptr, LengthUnit sz) => sz -> Src (ptr Word8) -> WriteTo
- writeByteString :: ByteString -> WriteTo
- transferSize :: Transfer t -> BYTES Int
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 ReadFrom = Transfer 'ReadFromBuffer Source #
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
first reads the the
data associated with <>
r2r1
and then reads the data associated with
r2
.
type WriteTo = Transfer 'WriteToBuffer Source #
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
first writes the
data associated from <>
w2w1
and then the writes the data associated
with w2
.
:: LengthUnit u | |
=> u | length of pointer accessed |
-> (Ptr Word8 -> IO ()) | Pointer action to run |
-> Transfer t |
Make an explicit transfer action.
:: 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 :: IO a -> Transfer t Source #
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.
:: (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.
:: 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 Source #
Write many elements from the given buffer
unsafeWriteFromPtr :: (Pointer ptr, LengthUnit sz) => sz -> Src (ptr Word8) -> WriteTo Source #
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 Source #
Writes a strict bytestring.