-- 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 0.6.0.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>io-streams</tt> with <tt>HsOpenSSL</tt>. <tt>ssl/SSL</tt> here
--   stand for <tt>HsOpenSSL</tt> library, not the deprecated SSL 2.0/3.0
--   protocol. the receive buffer size is 32752. sending is unbuffered,
--   anything write into <a>OutputStream</a> will be immediately send to
--   underlying socket.
--   
--   The same exceptions rule which applied to TCP apply here, with
--   addtional <a>SomeSSLException</a> to be watched out.
--   
--   This module is intended to be imported <tt>qualified</tt>, e.g.:
--   
--   <pre>
--   import qualified <a>System.IO.Streams.OpenSSL</a> as SSL
--   </pre>
module System.IO.Streams.OpenSSL

-- | Convenience function for initiating an SSL connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</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 (InputStream ByteString, OutputStream ByteString, SSL)

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

-- | Convenience function for initiating an SSL connection to the given
--   <tt>(<a>HostName</a>, <a>PortNumber</a>)</tt> combination. The socket
--   and SSL connection are closed and deleted after the user handler runs.
withConnection :: SSLContext -> Maybe String -> HostName -> PortNumber -> (InputStream ByteString -> OutputStream ByteString -> SSL -> IO a) -> IO a

-- | Accept a new connection from remote client, return a
--   <a>InputStream</a> / <a>OutputStream</a> 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 (InputStream ByteString, OutputStream ByteString, SSL, SockAddr)

-- | Given an existing HsOpenSSL <a>SSL</a> connection, produces an
--   <a>InputStream</a> / <a>OutputStream</a> pair.
sslToStreams :: SSL -> IO (InputStream ByteString, OutputStream ByteString)
close :: SSL -> IO ()
