| 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 | None |
| Language | Haskell2010 |
Raaz.Core
Description
Synopsis
- length :: ByteString -> BYTES Int
- replicate :: LengthUnit l => l -> Word8 -> ByteString
- create :: LengthUnit l => l -> (Ptr a -> IO ()) -> IO ByteString
- createFrom :: LengthUnit l => l -> Ptr a -> IO ByteString
- withByteString :: ByteString -> (Ptr something -> IO a) -> IO a
- unsafeCopyToPointer :: Pointer ptr => ByteString -> ptr a -> IO ()
- unsafeNCopyToPointer :: LengthUnit n => n -> ByteString -> Ptr a -> IO ()
- module Raaz.Core.Types
- module Raaz.Core.Transfer
- class (Unbox (WordType p), EndianStore (WordType p), KnownNat (WordsPerBlock p)) => Primitive p where
- type WordType p :: Type
- type WordsPerBlock p :: Nat
- data family Key p :: Type
- data family Nounce p :: Type
- type Block p = Tuple (WordsPerBlock p) (WordType p)
- type BlockPtr p = Ptr (Block p)
- type AlignedBlockPtr n p = AlignedPtr n (Block p)
- newtype BlockCount p = BlockCount {
- unBlockCount :: Int
- blocksOf :: Int -> Proxy p -> BlockCount p
- module Raaz.Core.Prelude
- module Raaz.Core.Encode
- l1Cache :: BYTES Int
- class ByteSource src where
- class ByteSource src => PureByteSource src
- data FillResult a
- fill :: (Pointer ptr, LengthUnit len, ByteSource src) => len -> src -> ptr a -> IO (FillResult src)
- processChunks :: (Pointer ptr, MonadIO m, LengthUnit chunkSize, ByteSource src) => m a -> (BYTES Int -> m b) -> src -> ptr something -> chunkSize -> m b
- withFillResult :: (a -> b) -> (BYTES Int -> b) -> FillResult a -> b
- data MemoryCell a
- class Memory mem => WriteAccessible mem where
- writeAccess :: mem -> [Access]
- afterWriteAdjustment :: mem -> IO ()
- class Memory mem => ReadAccessible mem where
- beforeReadAdjustment :: mem -> IO ()
- readAccess :: mem -> [Access]
- data Access
- class Memory m => Extractable m v where
- class Memory m => Initialisable m v where
- initialise :: v -> m -> IO ()
- data VoidMemory
- class Memory m where
- memoryAlloc :: Alloc m
- unsafeToPointer :: m -> Ptr Word8
- type Alloc mem = TwistRF AllocField (BYTES Int) mem
- pointerAlloc :: LengthUnit l => l -> Alloc (Ptr Word8)
- withMemoryPtr :: Memory m => (BYTES Int -> Ptr Word8 -> IO a) -> m -> IO a
- withMemory :: Memory mem => (mem -> IO a) -> IO a
- withSecureMemory :: Memory mem => (mem -> IO a) -> IO a
- modifyMem :: (Initialisable mem a, Extractable mem b) => (b -> a) -> mem -> IO ()
- memTransfer :: (ReadAccessible src, WriteAccessible dest) => Dest dest -> Src src -> IO ()
- unsafeGetCellPointer :: Storable a => MemoryCell a -> Ptr a
- withCellPointer :: Storable a => (Ptr a -> IO b) -> MemoryCell a -> IO b
- copyCell :: Storable a => Dest (MemoryCell a) -> Src (MemoryCell a) -> IO ()
Documentation
replicate :: LengthUnit l => l -> Word8 -> ByteString Source #
A type safe version of replicate
create :: LengthUnit l => l -> (Ptr a -> IO ()) -> IO ByteString Source #
The action create l act creates a length l bytestring where
the contents are filled using the the act to fill the buffer.
createFrom :: LengthUnit l => l -> Ptr a -> IO ByteString Source #
The IO action createFrom n cptr creates a bytestring by copying
n bytes from the pointer cptr.
withByteString :: ByteString -> (Ptr something -> IO a) -> IO a Source #
Works directly on the pointer associated with the
ByteString. This function should only read and not modify the
contents of the pointer.
Arguments
| :: Pointer ptr | |
| => ByteString | The source. |
| -> ptr a | The destination. |
| -> IO () |
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.
Arguments
| :: LengthUnit n | |
| => n | length of data to be copied |
| -> ByteString | The source byte string |
| -> Ptr a | The buffer |
| -> IO () |
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.
module Raaz.Core.Types
module Raaz.Core.Transfer
Cryptographic Primtives
class (Unbox (WordType p), EndianStore (WordType p), KnownNat (WordsPerBlock p)) => Primitive p Source #
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.
Associated Types
type WordType p :: Type Source #
The block which is the smallest unit of data that the primitive processes, is typically considered as an array of a particular word which is captured by the following associated type.
type WordsPerBlock p :: Nat Source #
The size of the array that forms the block. In particular, the block can be seen as an array of size `BlockArraySize p` of type `WORD p`.
Instances
| Primitive XChaCha20 Source # | |
Defined in Raaz.Primitive.ChaCha20.Internal | |
| Primitive ChaCha20 Source # | |
Defined in Raaz.Primitive.ChaCha20.Internal | |
| Primitive Poly1305 Source # | |
Defined in Raaz.Primitive.Poly1305.Internal | |
| Primitive prim => Primitive (Keyed prim) Source # | |
Defined in Raaz.Primitive.Keyed.Internal | |
data family Key p :: Type Source #
The type family that captures the key of a keyed primitive.
Instances
data family Nounce p :: Type Source #
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).
Instances
type AlignedBlockPtr n p = AlignedPtr n (Block p) Source #
Aligned version of block pointers.
newtype BlockCount p Source #
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.
Constructors
| BlockCount | |
Fields
| |
Instances
blocksOf :: Int -> Proxy p -> BlockCount p Source #
The expression n specifies the message
lengths in units of the block length of the primitive whose proxy
is blocksOf primProxyprimProxy. This expression is sometimes required to make the
type checker happy.
module Raaz.Core.Prelude
module Raaz.Core.Encode
Typical size of L1 cache. Used for selecting buffer size etc in crypto operations.
Byte sources.
Cryptographic input come from various sources; they can come from network sockets or might be just a string in the Haskell. To give a uniform interfaces for all such inputs, we define the abstract concept of a byte source. Essentially a byte source is one from which we can fill a buffer with bytes.
Among instances of ByteSource, some like for example
ByteString are pure in the sense filling a buffer with bytes
from such a source has no other side-effects. This is in contrast
to a source like a sockets. The type class PureByteSource
captures such byte sources.
class ByteSource src where Source #
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.
Methods
Arguments
| :: BYTES Int | Buffer size |
| -> src | The source to fill. |
| -> Ptr a | Buffer pointer |
| -> IO (FillResult src) |
Fills a buffer from the source.
Instances
| ByteSource Handle Source # | WARNING: The |
| ByteSource ByteString Source # | |
Defined in Raaz.Core.ByteSource Methods fillBytes :: BYTES Int -> ByteString -> Ptr a -> IO (FillResult ByteString) Source # | |
| ByteSource ByteString Source # | |
Defined in Raaz.Core.ByteSource Methods fillBytes :: BYTES Int -> ByteString -> Ptr a -> IO (FillResult ByteString) Source # | |
| ByteSource src => ByteSource [src] Source # | |
Defined in Raaz.Core.ByteSource | |
| ByteSource src => ByteSource (Maybe src) Source # | |
class ByteSource src => PureByteSource src Source #
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.
Instances
| PureByteSource ByteString Source # | |
Defined in Raaz.Core.ByteSource | |
| PureByteSource ByteString Source # | |
Defined in Raaz.Core.ByteSource | |
| PureByteSource src => PureByteSource [src] Source # | |
Defined in Raaz.Core.ByteSource | |
| PureByteSource src => PureByteSource (Maybe src) Source # | |
Defined in Raaz.Core.ByteSource | |
data FillResult a Source #
This type captures the result of a fill operation.
Constructors
| Remaining a | There is still bytes left. |
| Exhausted (BYTES Int) | source exhausted with so much bytes read. |
Instances
| Functor FillResult Source # | |
Defined in Raaz.Core.ByteSource Methods fmap :: (a -> b) -> FillResult a -> FillResult b # (<$) :: a -> FillResult b -> FillResult a # | |
| Eq a => Eq (FillResult a) Source # | |
Defined in Raaz.Core.ByteSource | |
| Show a => Show (FillResult a) Source # | |
Defined in Raaz.Core.ByteSource Methods showsPrec :: Int -> FillResult a -> ShowS # show :: FillResult a -> String # showList :: [FillResult a] -> ShowS # | |
fill :: (Pointer ptr, LengthUnit len, ByteSource src) => len -> src -> ptr a -> IO (FillResult src) Source #
A version of fillBytes that takes type safe lengths as input.
Arguments
| :: (Pointer ptr, MonadIO m, LengthUnit chunkSize, ByteSource src) | |
| => m a | action on a complete chunk, |
| -> (BYTES Int -> m b) | action on the last partial chunk, |
| -> src | the source |
| -> ptr something | buffer to fill the chunk in |
| -> chunkSize | size of the chunksize |
| -> m b |
Process data from a source in chunks of a particular size.
Arguments
| :: (a -> b) | stuff to do when filled |
| -> (BYTES Int -> b) | stuff to do when exhausted |
| -> FillResult a | the fill result to process |
| -> b |
Combinator to handle a fill result.
data MemoryCell a Source #
A memory location to store a value of type having Storable
instance.
Instances
class Memory mem => WriteAccessible mem where Source #
This class captures memories that can be initialised by writing bytes to (portions of) its buffer.
Methods
writeAccess :: mem -> [Access] Source #
The ordered access to buffers through which bytes may be written into the memory.
afterWriteAdjustment :: mem -> IO () Source #
After writing data into the buffer, the memory might need further adjustments before it is considered "initialised" with the sensitive data.
Instances
| WriteAccessible ChaCha20Mem Source # | Writes into the key portion. |
Defined in Raaz.Primitive.ChaCha20.Internal Methods writeAccess :: ChaCha20Mem -> [Access] Source # afterWriteAdjustment :: ChaCha20Mem -> IO () Source # | |
| EndianStore a => WriteAccessible (MemoryCell a) Source # | |
Defined in Raaz.Core.Memory Methods writeAccess :: MemoryCell a -> [Access] Source # afterWriteAdjustment :: MemoryCell a -> IO () Source # | |
class Memory mem => ReadAccessible mem where Source #
This class captures memories from which bytes can be extracted directly from (portions of) its buffer.
Methods
beforeReadAdjustment :: mem -> IO () Source #
Internal organisation of the data might need adjustment due to
host machine having a different endian than the standard byte
order of the associated type. This action perform the necessary
adjustment before the bytes can be read-off from the associated
readAccess adjustments.
readAccess :: mem -> [Access] Source #
The ordered access buffers for the memory through which bytes
may be read off (after running beforeReadAdjustment of course)
Instances
| EndianStore a => ReadAccessible (MemoryCell a) Source # | |
Defined in Raaz.Core.Memory Methods beforeReadAdjustment :: MemoryCell a -> IO () Source # readAccess :: MemoryCell a -> [Access] Source # | |
class Memory m => Extractable m v where Source #
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.
Instances
| Extractable ChaCha20Mem (BlockCount ChaCha20) Source # | |
Defined in Raaz.Primitive.ChaCha20.Internal Methods extract :: ChaCha20Mem -> IO (BlockCount ChaCha20) Source # | |
| Storable a => Extractable (MemoryCell a) a Source # | |
Defined in Raaz.Core.Memory Methods extract :: MemoryCell a -> IO a Source # | |
| Storable h => Extractable (HashMemory128 h) h Source # | |
Defined in Raaz.Primitive.HashMemory Methods extract :: HashMemory128 h -> IO h Source # | |
| Storable h => Extractable (HashMemory64 h) h Source # | |
Defined in Raaz.Primitive.HashMemory Methods extract :: HashMemory64 h -> IO h Source # | |
class Memory m => Initialisable m v where Source #
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.
Methods
initialise :: v -> m -> IO () Source #
Instances
data VoidMemory Source #
A memory element that holds nothing.
Instances
| Memory VoidMemory Source # | |
Defined in Raaz.Core.Memory | |
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
Methods
memoryAlloc :: Alloc m Source #
Returns an allocator for this memory.
unsafeToPointer :: m -> Ptr Word8 Source #
Returns the pointer to the underlying buffer.
Instances
type Alloc mem = TwistRF AllocField (BYTES Int) mem Source #
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.
pointerAlloc :: LengthUnit l => l -> Alloc (Ptr Word8) Source #
Allocates a buffer of size l and returns the pointer to it pointer.
withMemoryPtr :: Memory m => (BYTES Int -> Ptr Word8 -> IO a) -> m -> IO a Source #
Apply some low level action on the underlying buffer of the memory.
withMemory :: Memory mem => (mem -> IO a) -> IO a Source #
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.
withSecureMemory :: Memory mem => (mem -> IO a) -> IO a Source #
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.
modifyMem :: (Initialisable mem a, Extractable mem b) => (b -> a) -> mem -> IO () Source #
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) memmemTransfer :: (ReadAccessible src, WriteAccessible dest) => Dest dest -> Src src -> IO () Source #
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.
unsafeGetCellPointer :: Storable a => MemoryCell a -> Ptr a Source #
The location where the actual storing of element happens. This
pointer is guaranteed to be aligned to the alignment restriction of a
withCellPointer :: Storable a => (Ptr a -> IO b) -> MemoryCell a -> IO b Source #
Work with the underlying pointer of the memory cell. Useful while working with ffi functions.
copyCell :: Storable a => Dest (MemoryCell a) -> Src (MemoryCell a) -> IO () Source #
Copy the contents of one memory cell to another.