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


-- | Tcp streams using openssl for tls support.
--   
--   Tcp streams using openssl for tls support.
@package tcp-streams-openssl
@version 1.0.1.0


-- | Helpers for setting up a tls connection with <tt>HsOpenSSL</tt>
--   package, for further customization, please refer to <tt>HsOpenSSL</tt>
--   package.
--   
--   Note, functions in this module will throw error if can't load
--   certificates or CA store.
module Data.OpenSSLSetting

-- | The whole point of TLS is that: a peer should have already trusted
--   some certificates, which can be used for validating other peer's
--   certificates. if the certificates sent by other side form a chain. and
--   one of them is issued by one of <a>TrustedCAStore</a>, Then the peer
--   will be trusted.
data TrustedCAStore

-- | provided by your operating system.
SystemCAStore :: TrustedCAStore

-- | provided by <a>Mozilla</a>.
MozillaCAStore :: TrustedCAStore

-- | provided by your self, the CA file can contain multiple certificates.
CustomCAStore :: FilePath -> TrustedCAStore

-- | make a simple <a>SSLContext</a> that will validate server and use tls
--   connection without providing client's own certificate. suitable for
--   connecting server which don't validate clients.
makeClientSSLContext :: TrustedCAStore -> IO SSLContext

-- | make a simple <a>SSLContext</a> that will validate server and use tls
--   connection while providing client's own certificate. suitable for
--   connecting server which validate clients.
--   
--   The chain certificate must be in PEM format and must be sorted
--   starting with the subject's certificate (actual client or server
--   certificate), followed by intermediate CA certificates if applicable,
--   and ending at the highest level (root) CA.
makeClientSSLContext' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO SSLContext

-- | make a simple <a>SSLContext</a> for server without validating client's
--   certificate.
makeServerSSLContext :: FilePath -> [FilePath] -> FilePath -> IO SSLContext

-- | make a <a>SSLConext</a> that also validating client's certificate.
--   
--   This's an alias to <a>makeClientSSLContext'</a>.
makeServerSSLContext' :: FilePath -> [FilePath] -> FilePath -> TrustedCAStore -> IO SSLContext


-- | This module provides convenience functions for interfacing
--   <tt>HsOpenSSL</tt>. <tt>ssl/SSL</tt> here stand for <tt>HsOpenSSL</tt>
--   library, not the deprecated SSL 2.0/3.0 protocol.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import           <a>Data.Connection</a>
--   import qualified <a>System.IO.Streams.OpenSSL</a> as SSL
--   </pre>
module System.IO.Streams.OpenSSL

-- | Type alias for tls connection.
--   
--   Normally you shouldn't use <a>SSL</a> in <a>connExtraInfo</a>
--   directly.
type TLSConnection = Connection (SSL, SockAddr)

-- | Convenience function for initiating an SSL connection to the given
--   <tt>(<tt>HostName</tt>, <tt>PortNumber</tt>)</tt> combination.
--   
--   This function will try to verify server's identity using a very simple
--   algorithm, which may not suit your need:
--   
--   <pre>
--   matchDomain :: String -&gt; String -&gt; Bool
--   matchDomain n1 n2 =
--       let n1' = reverse (splitDot n1)
--           n2' = reverse (splitDot n2)
--           cmp src target = src == "*" || target == "*" || src == target
--       in and (zipWith cmp n1' n2')
--   </pre>
--   
--   If the certificate or hostname is not verified, a <a>ProtocolError</a>
--   will be thrown.
connect :: SSLContext -> Maybe String -> HostName -> PortNumber -> IO TLSConnection

-- | Connecting with a custom verification callback.
--   
--   <pre>
--   since 0.6.0.0
--   </pre>
connectWithVerifier :: SSLContext -> (Bool -> Maybe String -> Bool) -> HostName -> PortNumber -> IO TLSConnection

-- | Given an existing HsOpenSSL <tt>SSL</tt> connection, produces an
--   <tt>InputStream</tt> / <tt>OutputStream</tt> pair.
sslToConnection :: (SSL, SockAddr) -> IO TLSConnection

-- | Accept a new connection from remote client, return a
--   <tt>InputStream</tt> / <tt>OutputStream</tt> pair and remote
--   <a>SockAddr</a>, you should call <a>bindAndListen</a> first.
--   
--   this operation will throw <a>SomeSSLException</a> on failure.
accept :: SSLContext -> Socket -> IO TLSConnection
