Network.CommSec.Package

CommSec is a package that provides communication security for use with Haskell sockets. Using an ephemeral shared secret you can build contexts for sending or receiving data between one or more peers.

Do not reuse the shared secret! Key agreement mechanisms that leverage PKI might be added later.

Types

data OutContext

A context useful for sending data.

Constructors

Out

Fields

aesCtr :: !Word64

saltOut :: !Word32

outKey :: GCMdata

data InContext

A context useful for receiving data.

Constructors

In

Fields

bitWindow :: !BitWindow

saltIn :: !Word32

inKey :: GCMdata

InStrict

Fields

seqVal :: !Word64

saltIn :: !Word32

inKey :: GCMdata

InSequential

Fields

seqVal :: !Word64

saltIn :: !Word32

inKey :: GCMdata

data CommSecError

Errors that can be returned by the decoding/receicing operations.

Constructors

OldContext

DuplicateSeq

InvalidICV

BadPadding

BuildKeyFailure

Instances

Enum CommSecError

Eq CommSecError

Data CommSecError

Ord CommSecError

Show CommSecError

Typeable CommSecError

Exception CommSecError

data SequenceMode

Policy for misordered packets. Notice StrictOrdering does not mean every sequence numbered packet will be received, only that the sequence number will always increase.

Constructors

AllowOutOfOrder

StrictOrdering

Sequential

Instances

Enum SequenceMode

Eq SequenceMode

Data SequenceMode

Ord SequenceMode

Show SequenceMode

Typeable SequenceMode

Build contexts for use sending and receiving

newInContext :: ByteString -> SequenceMode -> InContext

Given at least 20 bytes of entropy, produce an in context that can communicate with an identically initialized out context.

newOutContext :: ByteString -> OutContext

Given at least 24 bytes of entropy, produce an out context that can communicate with an identically initialized in context.

Pure / ByteString based encryption and decryption routines

decode :: InContext -> ByteString -> Either CommSecError (ByteString, InContext)

Use an InContext to decrypt a message, verifying the ICV and sequence number. Unlike sending, receiving is more likely to result in an exceptional condition and thus it returns an Either value.

Message format: [ctr, ct, tag].

encode :: OutContext -> ByteString -> (ByteString, OutContext)

Use an OutContext to protect a message for transport. Message format: [ctr, ct, tag].

This routine can throw an exception of OldContext if the context being used has expired.

IO / Pointer based encryption and decryption routines

decodePtr :: InContext -> Ptr Word8 -> Ptr Word8 -> Int -> IO (Either CommSecError (Int, InContext))

decodePtr inCtx pkg msg pkgLen decrypts and verifies a package at location pkg of size pkgLen. The resulting message is placed at location msg and its size is returned along with a new context (or error).

encodePtr :: OutContext -> Ptr Word8 -> Ptr Word8 -> Int -> IO OutContext

encodePtr outCtx msg result msgLen will encode msgLen bytes at location msg, placing the result at location result. The buffer pointed to by result must be at least encBytes msgLen bytes large, the actual package will be exactly encBytes msgLen in size.

Utility functions

encBytes :: Int -> Int

Given a message length, returns the number of bytes an encoded message will consume.

decBytes :: Int -> Int

Given a package length, returns the number of bytes in the underlying message.

Wrappers for network sending and receiving

Utilities

peekBE32 :: Ptr Word8 -> IO Word32

pokeBE32 :: Ptr Word8 -> Word32 -> IO ()

peekBE :: Ptr Word8 -> IO Word64

pokeBE :: Ptr Word8 -> Word64 -> IO ()