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


-- | Abstraction over creating network connections with SOCKS5 and TLS
--   
--   This package provides an abstraction for communicating with
--   line-oriented network services while abstracting over the use of
--   SOCKS5 and TLS (via OpenSSL)
@package hookup
@version 0.8


module Hookup.OpenSSL
withDefaultPassword :: SSLContext -> Maybe ByteString -> IO a -> IO a

-- | Add hostname checking to the certificate verification step. Partial
--   wildcards matching is disabled.
installVerification :: SSLContext -> String -> IO ()
getPubKeyDer :: X509 -> IO ByteString

-- | Set the ciphers to be used by the given context for TLS 1.3
--   <a>https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_cipher_list.html</a>
--   
--   Unrecognised ciphers are ignored. If no ciphers from the list are
--   recognised, an exception is raised.
contextSetTls13Ciphers :: SSLContext -> String -> IO ()


-- | This module provides a uniform interface to network connections with
--   optional support for TLS and SOCKS.
--   
--   This library is careful to support both IPv4 and IPv6. It will attempt
--   to all of the addresses that a domain name resolves to until one the
--   first successful connection.
--   
--   Use <a>connect</a> and <a>close</a> to establish and close network
--   connections.
--   
--   Use <a>recv</a>, <a>recvLine</a>, and <a>send</a> to receive and
--   transmit data on an open network connection.
--   
--   TLS and SOCKS parameters can be provided. When both are provided a
--   connection will first be established to the SOCKS server and then the
--   TLS connection will be established through that proxy server. This is
--   most useful when connecting through a dynamic port forward of an SSH
--   client via the <tt>-D</tt> flag.
module Hookup

-- | A connection to a network service along with its read buffer used for
--   line-oriented protocols. The connection could be a plain network
--   connection, SOCKS connected, or TLS.
data Connection

-- | Open network connection to TCP service specified by the given
--   parameters.
--   
--   The resulting connection MUST be closed with <a>close</a> to avoid
--   leaking resources.
--   
--   Throws <a>IOError</a>, <a>SocksError</a>, <a>ProtocolError</a>,
--   <a>ConnectionFailure</a>
connect :: ConnectionParams -> IO Connection

-- | Create a new <a>Connection</a> using an already connected socket. This
--   will attempt to start TLS if configured but will ignore any SOCKS
--   server settings as it is assumed that the socket is already actively
--   connected to the intended service.
--   
--   Throws <a>ProtocolError</a>
connectWithSocket :: ConnectionParams -> Socket -> IO Connection

-- | Close network connection.
close :: Connection -> IO ()
upgradeTls :: TlsParams -> String -> Connection -> IO ()

-- | Receive the next chunk from the stream. This operation will first
--   return the buffer if it contains a non-empty chunk. Otherwise it will
--   request up to the requested number of bytes from the stream.
--   
--   Throws: <a>IOError</a>, <a>ConnectionAbruptlyTerminated</a>,
--   <a>ProtocolError</a>
recv :: Connection -> Int -> IO ByteString

-- | Receive a line from the network connection. Both <tt>"\r\n"</tt> and
--   <tt>"\n"</tt> are recognized.
--   
--   Returning <a>Nothing</a> means that the peer has closed its half of
--   the connection.
--   
--   Unterminated lines will raise a <a>LineTruncated</a> exception. This
--   can happen if the peer transmits some data and closes its end without
--   transmitting a line terminator.
--   
--   Throws: <a>ConnectionAbruptlyTerminated</a>, <a>ProtocolError</a>,
--   <a>ConnectionFailure</a>, <a>IOError</a>
recvLine :: Connection -> Int -> IO (Maybe ByteString)

-- | Send bytes on the network connection. This ensures the whole chunk is
--   transmitted, which might take multiple underlying sends.
--   
--   Throws: <a>IOError</a>, <a>ProtocolError</a>
send :: Connection -> ByteString -> IO ()

-- | Push a <a>ByteString</a> onto the buffer so that it will be the first
--   bytes to be read on the next receive operation. This could perhaps be
--   useful for putting the unused portion of a <a>recv</a> back into the
--   buffer for future <a>recvLine</a> or <a>recv</a> operations.
putBuf :: Connection -> ByteString -> IO ()

-- | Parameters for <a>connect</a>.
--   
--   Common defaults for fields: <tt>defaultFamily</tt>,
--   <a>defaultTlsParams</a>
--   
--   When a <a>SocksParams</a> is provided the connection will be
--   established using a SOCKS (version 5) proxy.
--   
--   When a <a>TlsParams</a> is provided the connection negotiate TLS at
--   connect time in order to protect the stream.
--   
--   The binding hostname can be used to force the connect to use a
--   particular interface or IP protocol version.
data ConnectionParams
ConnectionParams :: HostName -> PortNumber -> Maybe SocksParams -> Maybe TlsParams -> Maybe HostName -> ConnectionParams

-- | Destination host
[cpHost] :: ConnectionParams -> HostName

-- | Destination TCP port
[cpPort] :: ConnectionParams -> PortNumber

-- | Optional SOCKS parameters
[cpSocks] :: ConnectionParams -> Maybe SocksParams

-- | Optional TLS parameters
[cpTls] :: ConnectionParams -> Maybe TlsParams

-- | Source address to bind
[cpBind] :: ConnectionParams -> Maybe HostName

-- | SOCKS connection parameters
data SocksParams
SocksParams :: HostName -> PortNumber -> SocksAuthentication -> SocksParams

-- | SOCKS server host
[spHost] :: SocksParams -> HostName

-- | SOCKS server port
[spPort] :: SocksParams -> PortNumber

-- | SOCKS authentication method
[spAuth] :: SocksParams -> SocksAuthentication
data SocksAuthentication

-- | no credentials
NoSocksAuthentication :: SocksAuthentication

-- | RFC 1929 username and password
UsernamePasswordSocksAuthentication :: ByteString -> ByteString -> SocksAuthentication

-- | TLS connection parameters. These parameters are passed to OpenSSL when
--   making a secure connection.
data TlsParams
TlsParams :: Maybe FilePath -> Maybe FilePath -> Maybe ByteString -> Maybe FilePath -> String -> Maybe String -> TlsVerify -> TlsParams

-- | Path to client certificate
[tpClientCertificate] :: TlsParams -> Maybe FilePath

-- | Path to client private key
[tpClientPrivateKey] :: TlsParams -> Maybe FilePath

-- | Private key decryption password
[tpClientPrivateKeyPassword] :: TlsParams -> Maybe ByteString

-- | Path to CA certificate bundle
[tpServerCertificate] :: TlsParams -> Maybe FilePath

-- | OpenSSL cipher suite name (e.g. <tt>"HIGH"</tt>)
[tpCipherSuite] :: TlsParams -> String

-- | OpenSSL cipher suites for TLS 1.3
[tpCipherSuiteTls13] :: TlsParams -> Maybe String

-- | Hostname to use when checking certificate validity
[tpVerify] :: TlsParams -> TlsVerify
data TlsVerify

-- | Use the connection hostname to verify
VerifyDefault :: TlsVerify

-- | No verification
VerifyNone :: TlsVerify

-- | Use the given hostname to verify
VerifyHostname :: String -> TlsVerify

-- | <tt><a>PemPasswordSupply</a></tt> represents a way to supply password.
--   
--   FIXME: using PwTTY causes an error but I don't know why:
--   "error:0906406D:PEM routines:DEF_CALLBACK:problems getting password"
data PemPasswordSupply

-- | no password
PwNone :: PemPasswordSupply

-- | password in a static string
PwStr :: String -> PemPasswordSupply

-- | password in a static bytestring.
PwBS :: ByteString -> PemPasswordSupply

-- | get a password by a callback
PwCallback :: PemPasswordCallback -> PemPasswordSupply

-- | read a password from TTY
PwTTY :: PemPasswordSupply

-- | Default values for TLS that use no client certificates, use system CA
--   root, <tt>"HIGH"</tt> cipher suite, and which validate hostnames.
defaultTlsParams :: TlsParams

-- | Type for errors that can be thrown by this package.
data ConnectionFailure

-- | Failure during <tt>getAddrInfo</tt> resolving remote host
HostnameResolutionFailure :: HostName -> String -> ConnectionFailure

-- | Failure during <a>connect</a> to remote host
ConnectionFailure :: [ConnectError] -> ConnectionFailure

-- | Failure during <a>recvLine</a>
LineTooLong :: ConnectionFailure

-- | Incomplete line during <a>recvLine</a>
LineTruncated :: ConnectionFailure

-- | Socks command rejected by server by given reply code
SocksError :: CommandReply -> ConnectionFailure

-- | Socks authentication method was not accepted
SocksAuthenticationMethodRejected :: ConnectionFailure

-- | Socks authentication method was not accepted
SocksAuthenticationCredentialsRejected :: ConnectionFailure

-- | Username or password were too long
SocksBadAuthenticationCredentials :: ConnectionFailure

-- | Socks server sent an invalid message or no message.
SocksProtocolError :: ConnectionFailure

-- | Domain name was too long for SOCKS protocol
SocksBadDomainName :: ConnectionFailure

-- | SOCKS command reply codes
newtype CommandReply
CommandReply :: Word8 -> CommandReply
pattern Succeeded :: CommandReply
pattern GeneralFailure :: CommandReply
pattern NotAllowed :: CommandReply
pattern NetUnreachable :: CommandReply
pattern HostUnreachable :: CommandReply
pattern ConnectionRefused :: CommandReply
pattern TTLExpired :: CommandReply
pattern CmdNotSupported :: CommandReply
pattern AddrNotSupported :: CommandReply

-- | Get peer certificate if one exists.
getClientCertificate :: Connection -> IO (Maybe X509)

-- | Get peer certificate if one exists.
getPeerCertificate :: Connection -> IO (Maybe X509)
getPeerCertFingerprintSha1 :: Connection -> IO (Maybe ByteString)
getPeerCertFingerprintSha256 :: Connection -> IO (Maybe ByteString)
getPeerCertFingerprintSha512 :: Connection -> IO (Maybe ByteString)
getPeerPubkeyFingerprintSha1 :: Connection -> IO (Maybe ByteString)
getPeerPubkeyFingerprintSha256 :: Connection -> IO (Maybe ByteString)
getPeerPubkeyFingerprintSha512 :: Connection -> IO (Maybe ByteString)
instance GHC.Show.Show Hookup.SocksAuthentication
instance GHC.Show.Show Hookup.SocksParams
instance GHC.Show.Show Hookup.TlsVerify
instance GHC.Show.Show Hookup.TlsParams
instance GHC.Show.Show Hookup.ConnectionParams
instance GHC.Show.Show Hookup.ConnectError
instance GHC.Show.Show Hookup.ConnectionFailure
instance GHC.Exception.Type.Exception Hookup.ConnectionFailure
instance GHC.Exception.Type.Exception Hookup.ConnectError