-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Provide communications security using symmetric ephemeral keys
--   
--   This package provides confidentiallity, integrity and replay
--   detection. Users must provide ephemeral keys for one time use (reuse
--   will compromise the security guarentees). Starting with shared secret,
--   this package builds bi-directional channels for datagram based
--   communication.
@package commsec
@version 0.2.5

module Network.CommSec.Types

-- | Errors that can be returned by the decoding/receicing operations.
data CommSecError
OldContext :: CommSecError
DuplicateSeq :: CommSecError
InvalidICV :: CommSecError
BadPadding :: CommSecError

-- | Policy for misordered packets. Notice StrictOrdering does not mean
--   every sequence numbered packet will be received, only that the
--   sequence number will always increase.
data SequenceMode
AllowOutOfOrder :: SequenceMode
StrictOrdering :: SequenceMode
Sequential :: SequenceMode
instance Typeable CommSecError
instance Typeable SequenceMode
instance Eq CommSecError
instance Ord CommSecError
instance Show CommSecError
instance Enum CommSecError
instance Data CommSecError
instance Eq SequenceMode
instance Ord SequenceMode
instance Show SequenceMode
instance Enum SequenceMode
instance Data SequenceMode
instance Exception CommSecError

module Network.CommSec.BitWindow

-- | A Bit Window is just an unpacked tuple of base and mask
type BitWindow = (Word64, Word64)
zeroWindow :: BitWindow
updateBitWindow :: BitWindow -> Word64 -> Either CommSecError BitWindow


-- | 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.
module Network.CommSec.Package

-- | A context useful for sending data.
data OutContext
Out :: {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word32 -> AESKey -> OutContext
aesCtr :: OutContext -> {-# UNPACK #-} !Word64
saltOut :: OutContext -> {-# UNPACK #-} !Word32
outKey :: OutContext -> AESKey

-- | A context useful for receiving data.
data InContext
In :: {-# UNPACK #-} !BitWindow -> {-# UNPACK #-} !Word32 -> AESKey -> InContext
bitWindow :: InContext -> {-# UNPACK #-} !BitWindow
saltIn :: InContext -> {-# UNPACK #-} !Word32
inKey :: InContext -> AESKey
InStrict :: {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word32 -> AESKey -> InContext
seqVal :: InContext -> {-# UNPACK #-} !Word64
saltIn :: InContext -> {-# UNPACK #-} !Word32
inKey :: InContext -> AESKey
InSequential :: {-# UNPACK #-} !Word64 -> {-# UNPACK #-} !Word32 -> AESKey -> InContext
seqVal :: InContext -> {-# UNPACK #-} !Word64
saltIn :: InContext -> {-# UNPACK #-} !Word32
inKey :: InContext -> AESKey

-- | Errors that can be returned by the decoding/receicing operations.
data CommSecError
OldContext :: CommSecError
DuplicateSeq :: CommSecError
InvalidICV :: CommSecError
BadPadding :: CommSecError

-- | Policy for misordered packets. Notice StrictOrdering does not mean
--   every sequence numbered packet will be received, only that the
--   sequence number will always increase.
data SequenceMode
AllowOutOfOrder :: SequenceMode
StrictOrdering :: SequenceMode
Sequential :: SequenceMode

-- | Given at least 20 bytes of entropy, produce an in context that can
--   communicate with an identically initialized out context.
newInContext :: ByteString -> SequenceMode -> InContext

-- | Given at least 24 bytes of entropy, produce an out context that can
--   communicate with an identically initialized in context.
newOutContext :: ByteString -> OutContext

-- | Use an <a>InContext</a> 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 <a>Either</a> value.
--   
--   Message format: [ctr, ct, padding, tag].
decode :: InContext -> ByteString -> Either CommSecError (ByteString, InContext)

-- | Use an <a>OutContext</a> to protect a message for transport. Message
--   format: [ctr, ct, padding, tag].
--   
--   This routine can throw an exception of <a>OldContext</a> if the
--   context being used has expired.
encode :: OutContext -> ByteString -> (ByteString, OutContext)

-- | <tt>decodePtr inCtx pkg msg pkgLen</tt> decrypts and verifies a
--   package at location <tt>pkg</tt> of size <tt>pkgLen</tt>. The
--   resulting message is placed at location <tt>msg</tt> and its size is
--   returned along with a new context (or error).
decodePtr :: InContext -> Ptr Word8 -> Ptr Word8 -> Int -> IO (Either CommSecError (Int, InContext))

-- | <tt>encodePtr outCtx msg result msgLen</tt> will encode
--   <tt>msgLen</tt> bytes at location <tt>msg</tt>, placing the result at
--   location <tt>result</tt>. The buffer pointed to by <tt>result</tt>
--   must be at least <tt>encBytes msgLen</tt> bytes large, the actual
--   package will be exactly <tt>encBytes msgLen</tt> in size.
encodePtr :: OutContext -> Ptr Word8 -> Ptr Word8 -> Int -> IO OutContext

-- | Given a message length, returns the number of bytes an encoded message
--   will consume.
encBytes :: Int -> Int

-- | Given a package length, returns the maximum number of bytes the
--   underlying message could be (including padding).
decBytes :: Int -> Int
peekBE32 :: Ptr Word8 -> IO Word32
pokeBE32 :: Ptr Word8 -> Word32 -> IO ()
peekBE :: Ptr Word8 -> IO Word64
pokeBE :: Ptr Word8 -> Word64 -> IO ()

module Network.CommSec

-- | A connection is a secure bidirectional communication channel.
data Connection
Conn :: MVar InContext -> MVar OutContext -> Socket -> Connection
inCtx :: Connection -> MVar InContext
outCtx :: Connection -> MVar OutContext
socket :: Connection -> Socket

-- | Errors that can be returned by the decoding/receicing operations.
data CommSecError
OldContext :: CommSecError
DuplicateSeq :: CommSecError
InvalidICV :: CommSecError
BadPadding :: CommSecError

-- | Send a datagram, first encrypting it, using the given secure
--   connection.
send :: Connection -> ByteString -> IO ()

-- | Receive a datagram sent over the given secure connection
recv :: Connection -> IO ByteString

-- | Sends a message over the connection.
sendPtr :: Connection -> Ptr Word8 -> Int -> IO ()

-- | Blocks till it receives a valid message, placing the resulting
--   plaintext in the provided buffer. If the incoming message is larger
--   that the provided buffer then the message is truncated. This process
--   also incurs an additional copy.
recvPtr :: Connection -> Ptr Word8 -> Int -> IO Int

-- | Expands the provided 128 (or more) bit secret into two keys to create
--   a connection.
--   
--   ex: accept ent 3134
accept :: ByteString -> PortNumber -> IO Connection

-- | Expands the provided 128 (or more) bit secret into two keys to create
--   a connection.
connect :: ByteString -> HostName -> PortNumber -> IO Connection

-- | Close a connection
close :: Connection -> IO ()
expandSecret :: ByteString -> Int -> ByteString
instance Eq RecvRes