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


-- | Secure point-to-point connectivity library
--   
--   This library simplifies the task of securely connecting two servers to
--   each other, with strong authentication and encryption on the wire.
@package secure-sockets
@version 1.0


-- | This library simplifies the task of securely connecting two servers to
--   each other. It closely mimicks the regular socket API, and adds the
--   concept of identity: each communicating server has an identity, and
--   connections can only be established between two servers who know each
--   other and expect to be communicating.
--   
--   Under the hood, the library takes care of strongly authenticating the
--   connection, and of encrypting all traffic. If you successfully
--   establish a connection using this library, you have the guarantee that
--   the connection is secure.
module Network.Secure

-- | The public identity of a peer. This kind of identity can be used to
--   authenticate the remote ends of connections.
data PeerIdentity

-- | Serialize a <a>PeerIdentity</a> to a <a>ByteString</a> for storage or
--   transmission.
writePeerIdentity :: PeerIdentity -> IO ByteString

-- | Read back a <a>PeerIdentity</a> previously serialized with
--   <a>writePeerIdentity</a>.
readPeerIdentity :: ByteString -> IO PeerIdentity

-- | A local identity. This kind of identity can be used to authenticate
--   <i>to</i> remote ends of connections.
data LocalIdentity

-- | Serialize a <a>LocalIdentity</a> to a <a>ByteString</a> for storage.
writeLocalIdentity :: LocalIdentity -> IO ByteString

-- | Read back a <a>LocalIdentity</a> previously serialized with
--   <a>writeLocalIdentity</a>.
readLocalIdentity :: ByteString -> IO LocalIdentity

-- | Extract the public parts of a <a>LocalIdentity</a> into a
--   <a>PeerIdentity</a> suitable for sharing with peers. The resulting
--   <a>PeerIdentity</a> will allow them to verify your identity when you
--   authenticate using the corresponding <a>LocalIdentity</a>.
toPeerIdentity :: LocalIdentity -> PeerIdentity

-- | Generate a new <a>LocalIdentity</a>, giving it an identifying name and
--   a validity period in days.
--   
--   Note that this function may take quite a while to execute, as it is
--   generating key material for the identity.
newLocalIdentity :: String -> Int -> IO LocalIdentity

-- | Connect securely to the given host/port. The <a>Connection</a> is
--   returned only if the peer accepts the given <a>LocalIdentity</a>, and
--   if the remote endpoint successfully authenticates as the given
--   <a>PeerIdentity</a>.
connect :: LocalIdentity -> PeerIdentity -> (HostName, ServiceName) -> IO Connection

-- | A server socket that accepts only secure connections.
data Socket

-- | Create a new secure socket server, listening on the given
--   address/port. The host may be <a>Nothing</a> to signify that the
--   socket should listen on all available addresses.
newServer :: (Maybe HostName, ServiceName) -> IO Socket

-- | Accept one secure connection from a remote peer. The peer may
--   authenticate as any of the given peer identities. A <a>Connection</a>
--   is returned iff the autentication completes successfully.
accept :: LocalIdentity -> [PeerIdentity] -> Socket -> IO Connection

-- | An established authenticated connection to a peer. It is guaranteed
--   that all Connection objects are with a known peer, and that the
--   connection is strongly encrypted.
data Connection

-- | Return the <a>PeerIdentity</a> of the remote end of the connection.
peer :: Connection -> PeerIdentity

-- | Read at most <tt>n</tt> bytes from the given connection.
read :: Connection -> Int -> IO ByteString

-- | Send data to the connected peer.
write :: Connection -> ByteString -> IO ()

-- | Close the connection. No other operations on <a>Connection</a>s should
--   be used after closing it.
close :: Connection -> IO ()
type HostName = String
type ServiceName = String