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


-- | TLS bindings for Rustls
--   
--   TLS bindings for <a>Rustls</a> via <a>rustls-ffi</a>.
@package rustls
@version 0.0.1.0


-- | Internal module, not subject to PVP.
module Rustls.Internal.FFI
newtype ConstPtr a
ConstPtr :: Ptr a -> ConstPtr a
[unConstPtr] :: ConstPtr a -> Ptr a
type ConstCString = ConstPtr CChar
data {-# CTYPE "rustls.h" "rustls_client_config" #-} ClientConfig
data {-# CTYPE "rustls.h" "rustls_client_config_builder" #-} ClientConfigBuilder
clientConfigBuilderNewCustom :: ConstPtr (ConstPtr SupportedCipherSuite) -> CSize -> ConstPtr TLSVersion -> CSize -> Ptr (Ptr ClientConfigBuilder) -> IO Result
clientConfigBuilderFree :: Ptr ClientConfigBuilder -> IO ()
clientConfigBuilderBuild :: Ptr ClientConfigBuilder -> IO (ConstPtr ClientConfig)
clientConfigFree :: FinalizerPtr ClientConfig
clientConfigBuilderSetALPNProtocols :: Ptr ClientConfigBuilder -> ConstPtr SliceBytes -> CSize -> IO Result
clientConfigBuilderSetEnableSNI :: Ptr ClientConfigBuilder -> CBool -> IO ()
clientConfigBuilderSetCertifiedKey :: Ptr ClientConfigBuilder -> ConstPtr (ConstPtr CertifiedKey) -> CSize -> IO Result
clientConfigBuilderLoadRootsFromFile :: Ptr ClientConfigBuilder -> ConstCString -> IO Result
clientConfigBuilderUseRoots :: Ptr ClientConfigBuilder -> ConstPtr RootCertStore -> IO Result
clientConnectionNew :: ConstPtr ClientConfig -> ConstCString -> Ptr (Ptr Connection) -> IO Result
serverConnectionNew :: ConstPtr ServerConfig -> Ptr (Ptr Connection) -> IO Result
data {-# CTYPE "rustls.h" "rustls_server_config" #-} ServerConfig
data {-# CTYPE "rustls.h" "rustls_server_config_builder" #-} ServerConfigBuilder
serverConfigBuilderNewCustom :: ConstPtr (ConstPtr SupportedCipherSuite) -> CSize -> ConstPtr TLSVersion -> CSize -> Ptr (Ptr ServerConfigBuilder) -> IO Result
serverConfigBuilderFree :: Ptr ServerConfigBuilder -> IO ()
serverConfigBuilderBuild :: Ptr ServerConfigBuilder -> IO (ConstPtr ServerConfig)
serverConfigFree :: FinalizerPtr ServerConfig
serverConfigBuilderSetALPNProtocols :: Ptr ServerConfigBuilder -> ConstPtr SliceBytes -> CSize -> IO Result
serverConfigBuilderSetIgnoreClientOrder :: Ptr ServerConfigBuilder -> CBool -> IO Result
serverConfigBuilderSetCertifiedKeys :: Ptr ServerConfigBuilder -> ConstPtr (ConstPtr CertifiedKey) -> CSize -> IO Result
data {-# CTYPE "rustls.h" "rustls_client_cert_verifier" #-} ClientCertVerifier
clientCertVerifierNew :: ConstPtr RootCertStore -> IO (ConstPtr ClientCertVerifier)
clientCertVerifierFree :: ConstPtr ClientCertVerifier -> IO ()
serverConfigBuilderSetClientVerifier :: Ptr ServerConfigBuilder -> ConstPtr ClientCertVerifier -> IO ()
data {-# CTYPE "rustls.h" "rustls_client_cert_verifier_optional" #-} ClientCertVerifierOptional
clientCertVerifierOptionalNew :: ConstPtr RootCertStore -> IO (ConstPtr ClientCertVerifierOptional)
clientCertVerifierOptionalFree :: ConstPtr ClientCertVerifierOptional -> IO ()
serverConfigBuilderSetClientVerifierOptional :: Ptr ServerConfigBuilder -> ConstPtr ClientCertVerifierOptional -> IO ()
data {-# CTYPE "rustls.h" "rustls_certified_key" #-} CertifiedKey
certifiedKeyBuild :: ConstPtr Word8 -> CSize -> ConstPtr Word8 -> CSize -> Ptr (ConstPtr CertifiedKey) -> IO Result
certifiedKeyFree :: ConstPtr CertifiedKey -> IO ()
data {-# CTYPE "rustls.h" "rustls_certificate" #-} Certificate
certificateGetDER :: ConstPtr Certificate -> Ptr (ConstPtr Word8) -> Ptr CSize -> IO Result
data {-# CTYPE "rustls.h" "rustls_connection" #-} Connection
connectionFree :: Ptr Connection -> IO ()
type ReadCallback = Ptr Userdata -> Ptr Word8 -> CSize -> Ptr CSize -> IO IOResult
mkReadCallback :: ReadCallback -> IO (FunPtr ReadCallback)
connectionWantsRead :: ConstPtr Connection -> IO CBool
connectionRead :: Ptr Connection -> Ptr Word8 -> CSize -> Ptr CSize -> IO Result
connectionReadTls :: Ptr Connection -> FunPtr ReadCallback -> Ptr Userdata -> Ptr CSize -> IO IOResult
type WriteCallback = Ptr Userdata -> ConstPtr Word8 -> CSize -> Ptr CSize -> IO IOResult
mkWriteCallback :: WriteCallback -> IO (FunPtr WriteCallback)
connectionWantsWrite :: ConstPtr Connection -> IO CBool
connectionWrite :: Ptr Connection -> Ptr Word8 -> CSize -> Ptr CSize -> IO Result
connectionWriteTls :: Ptr Connection -> FunPtr WriteCallback -> Ptr Userdata -> Ptr CSize -> IO IOResult
connectionProcessNewPackets :: Ptr Connection -> IO Result
connectionIsHandshaking :: ConstPtr Connection -> IO CBool
connectionSendCloseNotify :: Ptr Connection -> IO ()
connectionSetBufferLimit :: Ptr Connection -> CSize -> IO ()
connectionGetALPNProtocol :: ConstPtr Connection -> Ptr (ConstPtr Word8) -> Ptr CSize -> IO ()
connectionGetProtocolVersion :: ConstPtr Connection -> IO TLSVersion
connectionGetNegotiatedCipherSuite :: ConstPtr Connection -> IO (ConstPtr SupportedCipherSuite)
serverConnectionGetSNIHostname :: ConstPtr Connection -> Ptr Word8 -> CSize -> Ptr CSize -> IO Result
connectionGetPeerCertificate :: ConstPtr Connection -> CSize -> IO (ConstPtr Certificate)
connectionSetLogCallback :: Ptr Connection -> FunPtr LogCallback -> IO ()
type LogCallback = Ptr Userdata -> ConstPtr LogParams -> IO ()
mkLogCallback :: LogCallback -> IO (FunPtr LogCallback)
data LogParams
LogParams :: LogLevel -> Str -> LogParams
[rustlsLogParamsLevel] :: LogParams -> LogLevel
[rustlsLogParamsMessage] :: LogParams -> Str
newtype LogLevel
LogLevel :: CSize -> LogLevel
data {-# CTYPE "rustls.h" "rustls_str" #-} Str
Str :: CString -> CSize -> Str
data {-# CTYPE "rustls.h" "rustls_slice_bytes" #-} SliceBytes
SliceBytes :: Ptr Word8 -> CSize -> SliceBytes
hsVersion :: Ptr Str -> IO ()

-- | (Unused) userdata.
data Userdata
newtype {-# CTYPE "rustls.h" "rustls_result" #-} Result
Result :: Word32 -> Result
resultIsCertError :: Result -> CBool
errorMsg :: Result -> CString -> CSize -> Ptr CSize -> IO ()
resultOk :: Result
resultInsufficientSize :: Result
newtype {-# CTYPE "rustls.h" "rustls_io_result" #-} IOResult
IOResult :: CInt -> IOResult
ioResultOk :: IOResult
ioResultErr :: IOResult
data {-# CTYPE "rustls.h" "rustls_supported_ciphersuite" #-} SupportedCipherSuite
allCipherSuites :: ConstPtr (Ptr SupportedCipherSuite)
allCipherSuitesLen :: CSize
defaultCipherSuites :: ConstPtr (ConstPtr SupportedCipherSuite)
defaultCipherSuitesLen :: CSize
supportedCipherSuiteGetSuite :: ConstPtr SupportedCipherSuite -> Word16
hsSupportedCipherSuiteGetName :: ConstPtr SupportedCipherSuite -> Ptr Str -> IO ()

-- | A TLS protocol version supported by Rustls.
newtype {-# CTYPE "stdint.h" "uint16_t" #-} TLSVersion
TLSVersion :: Word16 -> TLSVersion
[unTLSVersion] :: TLSVersion -> Word16
pattern TLS12 :: TLSVersion
pattern TLS13 :: TLSVersion
allVersions :: ConstPtr TLSVersion
allVersionsLen :: CSize
defaultVersions :: ConstPtr TLSVersion
defaultVersionsLen :: CSize
data {-# CTYPE "rustls.h" "rustls_root_cert_store" #-} RootCertStore
rootCertStoreNew :: IO (Ptr RootCertStore)
rootCertStoreAddPEM :: Ptr RootCertStore -> ConstPtr Word8 -> CSize -> CBool -> IO Result
rootCertStoreFree :: Ptr RootCertStore -> IO ()
instance Foreign.Storable.Storable (Rustls.Internal.FFI.ConstPtr a)
instance GHC.Classes.Eq (Rustls.Internal.FFI.ConstPtr a)
instance GHC.Show.Show (Rustls.Internal.FFI.ConstPtr a)
instance Foreign.Storable.Generic.Internal.GStorable Rustls.Internal.FFI.Str
instance GHC.Generics.Generic Rustls.Internal.FFI.Str
instance Foreign.Storable.Generic.Internal.GStorable Rustls.Internal.FFI.SliceBytes
instance GHC.Generics.Generic Rustls.Internal.FFI.SliceBytes
instance GHC.Classes.Ord Rustls.Internal.FFI.Result
instance GHC.Classes.Eq Rustls.Internal.FFI.Result
instance GHC.Show.Show Rustls.Internal.FFI.Result
instance GHC.Classes.Eq Rustls.Internal.FFI.IOResult
instance Foreign.Storable.Storable Rustls.Internal.FFI.LogLevel
instance GHC.Classes.Eq Rustls.Internal.FFI.LogLevel
instance GHC.Show.Show Rustls.Internal.FFI.LogLevel
instance Foreign.Storable.Generic.Internal.GStorable Rustls.Internal.FFI.LogParams
instance GHC.Generics.Generic Rustls.Internal.FFI.LogParams
instance Foreign.Storable.Storable Rustls.Internal.FFI.TLSVersion
instance GHC.Classes.Ord Rustls.Internal.FFI.TLSVersion
instance GHC.Classes.Eq Rustls.Internal.FFI.TLSVersion
instance GHC.Show.Show Rustls.Internal.FFI.TLSVersion


-- | Internal module, not subject to PVP.
module Rustls.Internal

-- | An ALPN protocol ID. See
--   <a>https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids</a>
--   for a list of registered IDs.
newtype ALPNProtocol
ALPNProtocol :: ByteString -> ALPNProtocol
[unALPNProtocol] :: ALPNProtocol -> ByteString

-- | A TLS cipher suite supported by Rustls.
newtype CipherSuite
CipherSuite :: ConstPtr SupportedCipherSuite -> CipherSuite

-- | Get the IANA value from a cipher suite. The bytes are interpreted in
--   network order.
--   
--   See
--   <a>https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4</a>
--   for a list.
cipherSuiteID :: CipherSuite -> Word16

-- | Get the text representation of a cipher suite.
showCipherSuite :: CipherSuite -> Text

-- | Rustls client config builder.
data ClientConfigBuilder
ClientConfigBuilder :: ClientRoots -> [TLSVersion] -> [CipherSuite] -> [ALPNProtocol] -> Bool -> [CertifiedKey] -> ClientConfigBuilder

-- | Client root certificates.
[clientConfigRoots] :: ClientConfigBuilder -> ClientRoots

-- | Supported <a>TLSVersion</a>s. When empty, good defaults are used.
[clientConfigTLSVersions] :: ClientConfigBuilder -> [TLSVersion]

-- | Supported <a>CipherSuite</a>s in order of preference. When empty, good
--   defaults are used.
[clientConfigCipherSuites] :: ClientConfigBuilder -> [CipherSuite]

-- | ALPN protocols.
[clientConfigALPNProtocols] :: ClientConfigBuilder -> [ALPNProtocol]

-- | Whether to enable Server Name Indication. Defaults to <a>True</a>.
[clientConfigEnableSNI] :: ClientConfigBuilder -> Bool

-- | List of <a>CertifiedKey</a>s for client authentication.
--   
--   Clients that want to support both ECDSA and RSA certificates will want
--   the ECDSA to go first in the list.
[clientConfigCertifiedKeys] :: ClientConfigBuilder -> [CertifiedKey]

-- | How to look up root certificates.
data ClientRoots

-- | Fetch PEM-encoded root certificates from a file.
ClientRootsFromFile :: FilePath -> ClientRoots

-- | Use in-memory PEM-encoded certificates.
ClientRootsInMemory :: [PEMCertificates] -> ClientRoots

-- | In-memory PEM-encoded certificates.
data PEMCertificates

-- | Syntactically valid PEM-encoded certificates.
PEMCertificatesStrict :: ByteString -> PEMCertificates

-- | PEM-encoded certificates, ignored if syntactically invalid.
--   
--   This may be useful on systems that have syntactically invalid root
--   certificates.
PEMCertificatesLax :: ByteString -> PEMCertificates

-- | A complete chain of certificates plus a private key for the leaf
--   certificate.
data CertifiedKey
CertifiedKey :: ByteString -> ByteString -> CertifiedKey

-- | PEM-encoded certificate chain.
[certificateChain] :: CertifiedKey -> ByteString

-- | PEM-encoded private key.
[privateKey] :: CertifiedKey -> ByteString

-- | Assembled configuration for a Rustls client connection.
data ClientConfig
ClientConfig :: ForeignPtr ClientConfig -> Maybe LogCallback -> ClientConfig
[clientConfigPtr] :: ClientConfig -> ForeignPtr ClientConfig

-- | A logging callback.
--   
--   Note that this is a record selector, so you can use it as a setter:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   setLogCallback :: LogCallback -&gt; ClientConfig -&gt; ClientConfig
--   setLogCallback logCallback clientConfig =
--     clientConfig { clientConfigLogCallback = Just logCallback }
--   :}
--   </pre>
[clientConfigLogCallback] :: ClientConfig -> Maybe LogCallback

-- | How to verify TLS client certificates.
data ClientCertVerifier

-- | Root certificates used to verify TLS client certificates.
ClientCertVerifier :: [PEMCertificates] -> ClientCertVerifier

-- | Root certificates used to verify TLS client certificates if present,
--   but does not reject clients which provide no certificate.
ClientCertVerifierOptional :: [PEMCertificates] -> ClientCertVerifier

-- | Rustls client config builder.
data ServerConfigBuilder
ServerConfigBuilder :: NonEmpty CertifiedKey -> [TLSVersion] -> [CipherSuite] -> [ALPNProtocol] -> Bool -> Maybe ClientCertVerifier -> ServerConfigBuilder

-- | List of <a>CertifiedKey</a>s.
[serverConfigCertifiedKeys] :: ServerConfigBuilder -> NonEmpty CertifiedKey

-- | Supported <a>TLSVersion</a>s. When empty, good defaults are used.
[serverConfigTLSVersions] :: ServerConfigBuilder -> [TLSVersion]

-- | Supported <a>CipherSuite</a>s in order of preference. When empty, good
--   defaults are used.
[serverConfigCipherSuites] :: ServerConfigBuilder -> [CipherSuite]

-- | ALPN protocols.
[serverConfigALPNProtocols] :: ServerConfigBuilder -> [ALPNProtocol]

-- | Ignore the client's ciphersuite order. Defaults to <a>False</a>.
[serverConfigIgnoreClientOrder] :: ServerConfigBuilder -> Bool

-- | Optionally, a client cert verifier.
[serverConfigClientCertVerifier] :: ServerConfigBuilder -> Maybe ClientCertVerifier

-- | Assembled configuration for a Rustls server connection.
data ServerConfig
ServerConfig :: ForeignPtr ServerConfig -> Maybe LogCallback -> ServerConfig
[serverConfigPtr] :: ServerConfig -> ForeignPtr ServerConfig

-- | A logging callback.
--   
--   Note that this is a record selector, so you can use it as a setter:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   setLogCallback :: LogCallback -&gt; ServerConfig -&gt; ServerConfig
--   setLogCallback logCallback serverConfig =
--     serverConfig { serverConfigLogCallback = Just logCallback }
--   :}
--   </pre>
[serverConfigLogCallback] :: ServerConfig -> Maybe LogCallback

-- | Rustls log level.
data LogLevel
LogLevelError :: LogLevel
LogLevelWarn :: LogLevel
LogLevelInfo :: LogLevel
LogLevelDebug :: LogLevel
LogLevelTrace :: LogLevel

-- | A Rustls connection logging callback.
newtype LogCallback
LogCallback :: FunPtr LogCallback -> LogCallback
[unLogCallback] :: LogCallback -> FunPtr LogCallback

-- | A <a>Monad</a> to get TLS connection information via <a>handshake</a>.
newtype HandshakeQuery (side :: Side) a
HandshakeQuery :: ReaderT Connection' IO a -> HandshakeQuery (side :: Side) a
handshakeQuery :: (Connection' -> IO a) -> HandshakeQuery side a

-- | TLS exception thrown by Rustls.
--   
--   Use <a>displayException</a> for a human-friendly representation.
newtype RustlsException
RustlsException :: Word32 -> RustlsException
[rustlsErrorCode] :: RustlsException -> Word32
resultMsg :: Result -> Text

-- | Checks if the given <a>RustlsException</a> represents a certificate
--   error.
isCertError :: RustlsException -> Bool
rethrowR :: Result -> IO ()

-- | Wrapper for exceptions thrown in a <a>LogCallback</a>.
newtype RustlsLogException
RustlsLogException :: SomeException -> RustlsLogException
data RustlsUnknownLogLevel
RustlsUnknownLogLevel :: LogLevel -> RustlsUnknownLogLevel

-- | Underlying data sources for Rustls.
class Backend b

-- | Read data from the backend into the given buffer.
backendRead :: Backend b => b -> Ptr Word8 -> CSize -> IO CSize

-- | Write data from the given buffer to the backend.
backendWrite :: Backend b => b -> Ptr Word8 -> CSize -> IO CSize

-- | An in-memory <a>Backend</a>.
data ByteStringBackend
ByteStringBackend :: (Int -> IO ByteString) -> (ByteString -> IO ()) -> ByteStringBackend

-- | Read a <a>ByteString</a> with the given max length.
[bsbRead] :: ByteStringBackend -> Int -> IO ByteString

-- | Write a <a>ByteString</a>.
[bsbWrite] :: ByteStringBackend -> ByteString -> IO ()

-- | Type-level indicator whether a <a>Connection</a> is client- or
--   server-side.
data Side
Client :: Side
Server :: Side

-- | A Rustls connection.
newtype Connection (side :: Side)
Connection :: MVar Connection' -> Connection (side :: Side)
data Connection'
Connection' :: Ptr Connection -> b -> Ptr CSize -> MVar IOMsgReq -> MVar IOMsgRes -> ThreadId -> Connection'
[conn] :: Connection' -> Ptr Connection
[backend] :: Connection' -> b
[lenPtr] :: Connection' -> Ptr CSize
[ioMsgReq] :: Connection' -> MVar IOMsgReq
[ioMsgRes] :: Connection' -> MVar IOMsgRes
[interactThread] :: Connection' -> ThreadId
withConnection :: Connection side -> (Connection' -> IO a) -> IO a
data ReadOrWrite
Read :: ReadOrWrite
Write :: ReadOrWrite

-- | Messages sent to the background thread.
data IOMsgReq

-- | Request to start a read or a write FFI call from the background
--   thread. It should respond with <a>UsingBuffer</a>.
Request :: ReadOrWrite -> IOMsgReq

-- | Notify the background thread that we are done interacting with the
--   buffer.
Done :: IOResult -> IOMsgReq

-- | Messages sent from the background thread.
data IOMsgRes

-- | Reply with a buffer, either containing the read data, or awaiting a
--   write to this buffer.
UsingBuffer :: Ptr Word8 -> CSize -> Ptr CSize -> IOMsgRes

-- | Notify that the FFI call finished.
DoneFFI :: IOMsgRes
interactTLS :: Connection' -> ReadOrWrite -> IO ()
data RunTLSMode
TLSHandshake :: RunTLSMode
TLSRead :: RunTLSMode
TLSWrite :: RunTLSMode
runTLS :: Connection' -> RunTLSMode -> IO ()
cSizeToInt :: CSize -> Int
intToCSize :: Int -> CSize
strToText :: Str -> IO Text
ignoreExceptions :: IO () -> IO ()
ignoreSyncExceptions :: IO () -> IO ()
instance GHC.Generics.Generic Rustls.Internal.ALPNProtocol
instance GHC.Classes.Ord Rustls.Internal.ALPNProtocol
instance GHC.Classes.Eq Rustls.Internal.ALPNProtocol
instance GHC.Show.Show Rustls.Internal.ALPNProtocol
instance GHC.Generics.Generic Rustls.Internal.PEMCertificates
instance GHC.Show.Show Rustls.Internal.PEMCertificates
instance GHC.Generics.Generic Rustls.Internal.ClientRoots
instance GHC.Generics.Generic Rustls.Internal.CertifiedKey
instance GHC.Generics.Generic Rustls.Internal.ClientConfigBuilder
instance GHC.Show.Show Rustls.Internal.ClientConfigBuilder
instance GHC.Generics.Generic Rustls.Internal.ClientCertVerifier
instance GHC.Show.Show Rustls.Internal.ClientCertVerifier
instance GHC.Generics.Generic Rustls.Internal.ServerConfigBuilder
instance GHC.Show.Show Rustls.Internal.ServerConfigBuilder
instance GHC.Generics.Generic Rustls.Internal.LogLevel
instance GHC.Enum.Bounded Rustls.Internal.LogLevel
instance GHC.Enum.Enum Rustls.Internal.LogLevel
instance GHC.Classes.Ord Rustls.Internal.LogLevel
instance GHC.Classes.Eq Rustls.Internal.LogLevel
instance GHC.Show.Show Rustls.Internal.LogLevel
instance GHC.Show.Show Rustls.Internal.RustlsException
instance GHC.Exception.Type.Exception Rustls.Internal.RustlsLogException
instance GHC.Show.Show Rustls.Internal.RustlsLogException
instance GHC.Exception.Type.Exception Rustls.Internal.RustlsUnknownLogLevel
instance GHC.Show.Show Rustls.Internal.RustlsUnknownLogLevel
instance GHC.Generics.Generic Rustls.Internal.ByteStringBackend
instance GHC.Base.Monad (Rustls.Internal.HandshakeQuery side)
instance GHC.Base.Applicative (Rustls.Internal.HandshakeQuery side)
instance GHC.Base.Functor (Rustls.Internal.HandshakeQuery side)
instance GHC.Classes.Eq Rustls.Internal.RunTLSMode
instance Rustls.Internal.Backend Rustls.Internal.ByteStringBackend
instance Rustls.Internal.Backend Network.Socket.Types.Socket
instance GHC.Exception.Type.Exception Rustls.Internal.RustlsException
instance GHC.Show.Show Rustls.Internal.CertifiedKey
instance GHC.Show.Show Rustls.Internal.ClientRoots
instance GHC.Classes.Eq Rustls.Internal.CipherSuite
instance GHC.Classes.Ord Rustls.Internal.CipherSuite
instance GHC.Show.Show Rustls.Internal.CipherSuite


-- | TLS bindings for <a>Rustls</a> via <a>rustls-ffi</a>.
--   
--   See the <a>README on GitHub</a> for setup instructions.
--   
--   Currently, most of the functionality exposed by rustls-ffi is
--   available, while rustls-ffi is still missing some more niche Rustls
--   features.
--   
--   Also see <a>http-client-rustls</a> for making HTTPS requests using
--   <a>http-client</a> and Rustls.
--   
--   <h2>Client example</h2>
--   
--   Suppose you have alread opened a <a>Socket</a> to
--   <tt>example.org</tt>, port 443 (see e.g. the examples at
--   <a>Network.Socket</a>). This small example showcases how to perform a
--   simple HTTP GET request:
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings
--   
--   &gt;&gt;&gt; import qualified Rustls
--   
--   &gt;&gt;&gt; import Network.Socket (Socket)
--   
--   &gt;&gt;&gt; import Data.Acquire (withAcquire)
--   
--   &gt;&gt;&gt; :{
--   example :: Socket -&gt; IO ()
--   example socket = do
--     -- It is encouraged to share a single `clientConfig` when creating multiple
--     -- TLS connections.
--     clientConfig &lt;-
--       Rustls.buildClientConfig $ Rustls.defaultClientConfigBuilder roots
--     let newConnection =
--           Rustls.newClientConnection socket clientConfig "example.org"
--     withAcquire newConnection $ \conn -&gt; do
--       Rustls.writeBS conn "GET /"
--       recv &lt;- Rustls.readBS conn 1000 -- max number of bytes to read
--       print recv
--     where
--       -- For now, rustls-ffi does not provide a built-in way to access
--       -- the OS certificate store.
--       roots = Rustls.ClientRootsFromFile "/etc/ssl/certs/ca-certificates.crt"
--   :}
--   </pre>
--   
--   <h2>Using <a>Acquire</a></h2>
--   
--   Some API functions (like <a>newClientConnection</a> and
--   <a>newServerConnection</a>) return an <a>Acquire</a> from
--   <a>resourcet</a>, as it is a convenient abstraction for exposing a
--   value that should be consumed in a "bracketed" manner.
--   
--   Usually, it can be used via <a>with</a> or <a>withAcquire</a>, or via
--   <a>allocateAcquire</a> when a <a>MonadResource</a> constraint is
--   available. If you really need the extra flexibility, you can also
--   access separate <tt>open…</tt> and <tt>close…</tt> functions by
--   reaching for <a>Data.Acquire.Internal</a>.
module Rustls

-- | Rustls client config builder.
data ClientConfigBuilder
ClientConfigBuilder :: ClientRoots -> [TLSVersion] -> [CipherSuite] -> [ALPNProtocol] -> Bool -> [CertifiedKey] -> ClientConfigBuilder

-- | Client root certificates.
[clientConfigRoots] :: ClientConfigBuilder -> ClientRoots

-- | Supported <a>TLSVersion</a>s. When empty, good defaults are used.
[clientConfigTLSVersions] :: ClientConfigBuilder -> [TLSVersion]

-- | Supported <a>CipherSuite</a>s in order of preference. When empty, good
--   defaults are used.
[clientConfigCipherSuites] :: ClientConfigBuilder -> [CipherSuite]

-- | ALPN protocols.
[clientConfigALPNProtocols] :: ClientConfigBuilder -> [ALPNProtocol]

-- | Whether to enable Server Name Indication. Defaults to <a>True</a>.
[clientConfigEnableSNI] :: ClientConfigBuilder -> Bool

-- | List of <a>CertifiedKey</a>s for client authentication.
--   
--   Clients that want to support both ECDSA and RSA certificates will want
--   the ECDSA to go first in the list.
[clientConfigCertifiedKeys] :: ClientConfigBuilder -> [CertifiedKey]

-- | A <a>ClientConfigBuilder</a> with good defaults.
defaultClientConfigBuilder :: ClientRoots -> ClientConfigBuilder

-- | How to look up root certificates.
data ClientRoots

-- | Fetch PEM-encoded root certificates from a file.
ClientRootsFromFile :: FilePath -> ClientRoots

-- | Use in-memory PEM-encoded certificates.
ClientRootsInMemory :: [PEMCertificates] -> ClientRoots

-- | In-memory PEM-encoded certificates.
data PEMCertificates

-- | Syntactically valid PEM-encoded certificates.
PEMCertificatesStrict :: ByteString -> PEMCertificates

-- | PEM-encoded certificates, ignored if syntactically invalid.
--   
--   This may be useful on systems that have syntactically invalid root
--   certificates.
PEMCertificatesLax :: ByteString -> PEMCertificates

-- | Assembled configuration for a Rustls client connection.
data ClientConfig

-- | A logging callback.
--   
--   Note that this is a record selector, so you can use it as a setter:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   setLogCallback :: LogCallback -&gt; ClientConfig -&gt; ClientConfig
--   setLogCallback logCallback clientConfig =
--     clientConfig { clientConfigLogCallback = Just logCallback }
--   :}
--   </pre>
clientConfigLogCallback :: ClientConfig -> Maybe LogCallback

-- | Build a <a>ClientConfigBuilder</a> into a <a>ClientConfig</a>.
--   
--   This is a relatively expensive operation, so it is a good idea to
--   share one <a>ClientConfig</a> when creating multiple
--   <a>Connection</a>s.
buildClientConfig :: MonadIO m => ClientConfigBuilder -> m ClientConfig

-- | Initialize a TLS connection as a client.
newClientConnection :: Backend b => b -> ClientConfig -> Text -> Acquire (Connection Client)

-- | Rustls client config builder.
data ServerConfigBuilder
ServerConfigBuilder :: NonEmpty CertifiedKey -> [TLSVersion] -> [CipherSuite] -> [ALPNProtocol] -> Bool -> Maybe ClientCertVerifier -> ServerConfigBuilder

-- | List of <a>CertifiedKey</a>s.
[serverConfigCertifiedKeys] :: ServerConfigBuilder -> NonEmpty CertifiedKey

-- | Supported <a>TLSVersion</a>s. When empty, good defaults are used.
[serverConfigTLSVersions] :: ServerConfigBuilder -> [TLSVersion]

-- | Supported <a>CipherSuite</a>s in order of preference. When empty, good
--   defaults are used.
[serverConfigCipherSuites] :: ServerConfigBuilder -> [CipherSuite]

-- | ALPN protocols.
[serverConfigALPNProtocols] :: ServerConfigBuilder -> [ALPNProtocol]

-- | Ignore the client's ciphersuite order. Defaults to <a>False</a>.
[serverConfigIgnoreClientOrder] :: ServerConfigBuilder -> Bool

-- | Optionally, a client cert verifier.
[serverConfigClientCertVerifier] :: ServerConfigBuilder -> Maybe ClientCertVerifier

-- | A <a>ServerConfigBuilder</a> with good defaults.
defaultServerConfigBuilder :: NonEmpty CertifiedKey -> ServerConfigBuilder

-- | How to verify TLS client certificates.
data ClientCertVerifier

-- | Root certificates used to verify TLS client certificates.
ClientCertVerifier :: [PEMCertificates] -> ClientCertVerifier

-- | Root certificates used to verify TLS client certificates if present,
--   but does not reject clients which provide no certificate.
ClientCertVerifierOptional :: [PEMCertificates] -> ClientCertVerifier

-- | Assembled configuration for a Rustls server connection.
data ServerConfig

-- | A logging callback.
--   
--   Note that this is a record selector, so you can use it as a setter:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   setLogCallback :: LogCallback -&gt; ServerConfig -&gt; ServerConfig
--   setLogCallback logCallback serverConfig =
--     serverConfig { serverConfigLogCallback = Just logCallback }
--   :}
--   </pre>
serverConfigLogCallback :: ServerConfig -> Maybe LogCallback

-- | Build a <a>ServerConfigBuilder</a> into a <a>ServerConfig</a>.
--   
--   This is a relatively expensive operation, so it is a good idea to
--   share one <a>ServerConfig</a> when creating multiple
--   <a>Connection</a>s.
buildServerConfig :: MonadIO m => ServerConfigBuilder -> m ServerConfig

-- | Initialize a TLS connection as a server.
newServerConnection :: Backend b => b -> ServerConfig -> Acquire (Connection Server)

-- | A Rustls connection.
data Connection (side :: Side)

-- | Type-level indicator whether a <a>Connection</a> is client- or
--   server-side.
data Side
Client :: Side
Server :: Side

-- | Read data from the Rustls <a>Connection</a> into a <a>ByteString</a>.
--   The result will not be longer than the given length.
readBS :: MonadIO m => Connection side -> Int -> m ByteString

-- | Write a <a>ByteString</a> to the Rustls <a>Connection</a>.
writeBS :: MonadIO m => Connection side -> ByteString -> m ()

-- | Ensure that the connection is handshaked. It is only necessary to call
--   this if you want to obtain connection information. You can do so by
--   providing a <a>HandshakeQuery</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   getALPNAndTLSVersion ::
--     MonadIO m =&gt;
--     Connection side -&gt;
--     m (Maybe ALPNProtocol, TLSVersion)
--   getALPNAndTLSVersion conn =
--     handshake conn $ (,) &lt;$&gt; getALPNProtocol &lt;*&gt; getTLSVersion
--   :}
--   </pre>
handshake :: MonadIO m => Connection side -> HandshakeQuery side a -> m a

-- | A <a>Monad</a> to get TLS connection information via <a>handshake</a>.
data HandshakeQuery (side :: Side) a

-- | Get the negotiated ALPN protocol, if any.
getALPNProtocol :: HandshakeQuery side (Maybe ALPNProtocol)

-- | Get the negotiated TLS protocol version.
getTLSVersion :: HandshakeQuery side TLSVersion

-- | Get the negotiated cipher suite.
getCipherSuite :: HandshakeQuery side CipherSuite

-- | Get the SNI hostname set by the client, if any.
getSNIHostname :: HandshakeQuery Server (Maybe Text)

-- | Get the <tt>i</tt>-th certificate provided by the peer.
--   
--   Index <tt>0</tt> is the end entity certificate. Higher indices are
--   certificates in the chain. Requesting an index higher than what is
--   available returns <a>Nothing</a>.
getPeerCertificate :: CSize -> HandshakeQuery side (Maybe DERCertificate)

-- | Send a <tt>close_notify</tt> warning alert. This informs the peer that
--   the connection is being closed.
sendCloseNotify :: MonadIO m => Connection side -> m ()

-- | A Rustls connection logging callback.
data LogCallback

-- | Allocate a new logging callback, taking a <a>LogLevel</a> and a
--   message.
--   
--   If it throws an exception, it will be wrapped in a
--   <a>RustlsLogException</a> and passed to <a>reportError</a>.
--   
--   🚫 Make sure that its lifetime encloses those of the <a>Connection</a>s
--   which you configured to use it.
newLogCallback :: (LogLevel -> Text -> IO ()) -> Acquire LogCallback

-- | Rustls log level.
data LogLevel
LogLevelError :: LogLevel
LogLevelWarn :: LogLevel
LogLevelInfo :: LogLevel
LogLevelDebug :: LogLevel
LogLevelTrace :: LogLevel

-- | Read data from the Rustls <a>Connection</a> into the given buffer.
readPtr :: MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize

-- | Write data to the Rustls <a>Connection</a> from the given buffer.
writePtr :: MonadIO m => Connection side -> Ptr Word8 -> CSize -> m CSize

-- | Combined version string of Rustls and rustls-ffi.
--   
--   <pre>
--   &gt;&gt;&gt; version
--   "rustls-ffi/0.9.2/rustls/0.20.8"
--   </pre>
version :: Text

-- | Underlying data sources for Rustls.
class Backend b

-- | Read data from the backend into the given buffer.
backendRead :: Backend b => b -> Ptr Word8 -> CSize -> IO CSize

-- | Write data from the given buffer to the backend.
backendWrite :: Backend b => b -> Ptr Word8 -> CSize -> IO CSize

-- | An in-memory <a>Backend</a>.
data ByteStringBackend
ByteStringBackend :: (Int -> IO ByteString) -> (ByteString -> IO ()) -> ByteStringBackend

-- | Read a <a>ByteString</a> with the given max length.
[bsbRead] :: ByteStringBackend -> Int -> IO ByteString

-- | Write a <a>ByteString</a>.
[bsbWrite] :: ByteStringBackend -> ByteString -> IO ()

-- | An ALPN protocol ID. See
--   <a>https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids</a>
--   for a list of registered IDs.
newtype ALPNProtocol
ALPNProtocol :: ByteString -> ALPNProtocol
[unALPNProtocol] :: ALPNProtocol -> ByteString

-- | A complete chain of certificates plus a private key for the leaf
--   certificate.
data CertifiedKey
CertifiedKey :: ByteString -> ByteString -> CertifiedKey

-- | PEM-encoded certificate chain.
[certificateChain] :: CertifiedKey -> ByteString

-- | PEM-encoded private key.
[privateKey] :: CertifiedKey -> ByteString

-- | A DER-encoded certificate.
newtype DERCertificate
DERCertificate :: ByteString -> DERCertificate
[unDERCertificate] :: DERCertificate -> ByteString

-- | A TLS protocol version supported by Rustls.
data {-# CTYPE "stdint.h" "uint16_t" #-} TLSVersion
pattern TLS12 :: TLSVersion
pattern TLS13 :: TLSVersion

-- | The default <a>TLSVersion</a>s used by Rustls. A subset of
--   <a>allTLSVersions</a>.
defaultTLSVersions :: NonEmpty TLSVersion

-- | All <a>TLSVersion</a>s supported by Rustls.
allTLSVersions :: NonEmpty TLSVersion

-- | A TLS cipher suite supported by Rustls.
data CipherSuite

-- | Get the IANA value from a cipher suite. The bytes are interpreted in
--   network order.
--   
--   See
--   <a>https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-4</a>
--   for a list.
cipherSuiteID :: CipherSuite -> Word16

-- | Get the text representation of a cipher suite.
showCipherSuite :: CipherSuite -> Text

-- | The default <a>CipherSuite</a>s used by Rustls. A subset of
--   <a>allCipherSuites</a>.
defaultCipherSuites :: NonEmpty CipherSuite

-- | All <a>CipherSuite</a>s supported by Rustls.
allCipherSuites :: NonEmpty CipherSuite

-- | TLS exception thrown by Rustls.
--   
--   Use <a>displayException</a> for a human-friendly representation.
data RustlsException

-- | Checks if the given <a>RustlsException</a> represents a certificate
--   error.
isCertError :: RustlsException -> Bool

-- | Wrapper for exceptions thrown in a <a>LogCallback</a>.
newtype RustlsLogException
RustlsLogException :: SomeException -> RustlsLogException
instance GHC.Generics.Generic Rustls.DERCertificate
instance GHC.Classes.Ord Rustls.DERCertificate
instance GHC.Classes.Eq Rustls.DERCertificate
instance GHC.Show.Show Rustls.DERCertificate