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


-- | TLS protocol native implementation
--   
--   Native Haskell TLS 1.2/1.3 protocol implementation for servers and
--   clients.
@package tls
@version 2.1.8


-- | Finite Field Diffie-Hellman Ephemeral Parameters defined in RFC 7919.
module Network.TLS.Extra.FFDHE

-- | 2048 bits finite field Diffie-Hellman ephemeral parameters defined in
--   RFC 7919. The estimated symmetric-equivalent strength is 103 bits.
ffdhe2048 :: DHParams

-- | 3072 bits finite field Diffie-Hellman ephemeral parameters defined in
--   RFC 7919. The estimated symmetric-equivalent strength is 125 bits.
ffdhe3072 :: DHParams

-- | 4096 bits finite field Diffie-Hellman ephemeral parameters defined in
--   RFC 7919. The estimated symmetric-equivalent strength is 150 bits.
ffdhe4096 :: DHParams

-- | 6144 bits finite field Diffie-Hellman ephemeral parameters defined in
--   RFC 7919. The estimated symmetric-equivalent strength is 175 bits.
ffdhe6144 :: DHParams

-- | 8192 bits finite field Diffie-Hellman ephemeral parameters defined in
--   RFC 7919. The estimated symmetric-equivalent strength is 192 bits.
ffdhe8192 :: DHParams

module Network.TLS.Extra.Cipher

-- | All AES and ChaCha20-Poly1305 ciphers supported ordered from strong to
--   weak. This choice of ciphersuites should satisfy most normal needs.
--   For otherwise strong ciphers we make little distinction between AES128
--   and AES256, and list each but the weakest of the AES128 ciphers ahead
--   of the corresponding AES256 ciphers.
--   
--   AEAD ciphers with equivalent security properties are ordered based on
--   CPU hardware-acceleration support. If this dynamic runtime behavior is
--   not desired, use <a>ciphersuite_default_det</a> instead.
ciphersuite_default :: [Cipher]

-- | Same as <a>ciphersuite_default</a>, but using deterministic preference
--   not influenced by the CPU.
ciphersuite_default_det :: [Cipher]

-- | The default ciphersuites + some not recommended last resort ciphers.
--   
--   AEAD ciphers with equivalent security properties are ordered based on
--   CPU hardware-acceleration support. If this dynamic runtime behavior is
--   not desired, use <a>ciphersuite_all_det</a> instead.
ciphersuite_all :: [Cipher]

-- | Same as <a>ciphersuite_all</a>, but using deterministic preference not
--   influenced by the CPU.
ciphersuite_all_det :: [Cipher]

-- | The strongest ciphers supported. For ciphers with PFS, AEAD and SHA2,
--   we list each AES128 variant after the corresponding AES256 and
--   ChaCha20-Poly1305 variants. For weaker constructs, we use just the
--   AES256 form.
--   
--   AEAD ciphers with equivalent security properties are ordered based on
--   CPU hardware-acceleration support. If this dynamic runtime behavior is
--   not desired, use <a>ciphersuite_strong_det</a> instead.
ciphersuite_strong :: [Cipher]

-- | Same as <a>ciphersuite_strong</a>, but using deterministic preference
--   not influenced by the CPU.
ciphersuite_strong_det :: [Cipher]

-- | DHE-RSA cipher suite. This only includes ciphers bound specifically to
--   DHE-RSA so TLS 1.3 ciphers must be added separately.
ciphersuite_dhe_rsa :: [Cipher]
cipher_DHE_RSA_WITH_AES_128_GCM_SHA256 :: Cipher
cipher_DHE_RSA_WITH_AES_256_GCM_SHA384 :: Cipher
cipher13_AES_128_GCM_SHA256 :: Cipher
cipher13_AES_256_GCM_SHA384 :: Cipher
cipher13_CHACHA20_POLY1305_SHA256 :: Cipher
cipher13_AES_128_CCM_SHA256 :: Cipher
cipher13_AES_128_CCM_8_SHA256 :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 :: Cipher
cipher_ECDHE_RSA_WITH_AES_128_GCM_SHA256 :: Cipher
cipher_ECDHE_RSA_WITH_AES_256_GCM_SHA384 :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_128_CCM :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_256_CCM :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_128_CCM_8 :: Cipher
cipher_ECDHE_ECDSA_WITH_AES_256_CCM_8 :: Cipher
cipher_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 :: Cipher
cipher_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 :: Cipher
cipher_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_DHE_RSA_WITH_AES_128_GCM_SHA256 instead</i>
cipher_DHE_RSA_AES128GCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_DHE_RSA_WITH_AES_256_GCM_SHA384 instead</i>
cipher_DHE_RSA_AES256GCM_SHA384 :: Cipher

-- | <i>Deprecated: Use cipher13_AES_128_GCM_SHA256 instead</i>
cipher_TLS13_AES128GCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher13_AES_256_GCM_SHA384 instead</i>
cipher_TLS13_AES256GCM_SHA384 :: Cipher

-- | <i>Deprecated: Use cipher13_CHACHA20_POLY1305_SHA256 instead</i>
cipher_TLS13_CHACHA20POLY1305_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher13_AES_128_CCM_SHA256 instead</i>
cipher_TLS13_AES128CCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher13_AES_128_CCM_8_SHA256 instead</i>
cipher_TLS13_AES128CCM8_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
--   instead</i>
cipher_ECDHE_ECDSA_AES128GCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
--   instead</i>
cipher_ECDHE_ECDSA_AES256GCM_SHA384 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_RSA_WITH_AES_128_GCM_SHA256
--   instead</i>
cipher_ECDHE_RSA_AES128GCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_RSA_WITH_AES_256_GCM_SHA384
--   instead</i>
cipher_ECDHE_RSA_AES256GCM_SHA384 :: Cipher

-- | <i>Deprecated: User cipher_ECDHE_ECDSA_WITH_AES_128_CCM instead</i>
cipher_ECDHE_ECDSA_AES128CCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_AES_256_CCM instead</i>
cipher_ECDHE_ECDSA_AES256CCM_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_AES_128_CCM_8 instead</i>
cipher_ECDHE_ECDSA_AES128CCM8_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_AES_256_CCM_8 instead</i>
cipher_ECDHE_ECDSA_AES256CCM8_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
--   instead</i>
cipher_ECDHE_RSA_CHACHA20POLY1305_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
--   instead</i>
cipher_ECDHE_ECDSA_CHACHA20POLY1305_SHA256 :: Cipher

-- | <i>Deprecated: Use cipher_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256
--   instead</i>
cipher_DHE_RSA_CHACHA20POLY1305_SHA256 :: Cipher


-- | Default values and ciphers
module Network.TLS.Extra


-- | API to run the TLS handshake establishing a QUIC connection.
--   
--   On the northbound API:
--   
--   <ul>
--   <li>QUIC starts a TLS client or server thread with
--   <a>tlsQUICClient</a> or <a>tlsQUICServer</a>.</li>
--   </ul>
--   
--   TLS invokes QUIC callbacks to use the QUIC transport
--   
--   <ul>
--   <li>TLS uses <a>quicSend</a> and <a>quicRecv</a> to send and receive
--   handshake message fragments.</li>
--   <li>TLS calls <a>quicInstallKeys</a> to provide to QUIC the traffic
--   secrets it should use for encryption/decryption.</li>
--   <li>TLS calls <a>quicNotifyExtensions</a> to notify to QUIC the
--   transport parameters exchanged through the handshake protocol.</li>
--   <li>TLS calls <a>quicDone</a> when the handshake is done.</li>
--   </ul>
module Network.TLS.QUIC

-- | Start a TLS handshake thread for a QUIC client. The client will use
--   the specified TLS parameters and call the provided callback functions
--   to send and receive handshake data.
tlsQUICClient :: ClientParams -> QUICCallbacks -> IO ()

-- | Start a TLS handshake thread for a QUIC server. The server will use
--   the specified TLS parameters and call the provided callback functions
--   to send and receive handshake data.
tlsQUICServer :: ServerParams -> QUICCallbacks -> IO ()

-- | Callbacks implemented by QUIC and to be called by TLS at specific
--   points during the handshake. TLS may invoke them from external threads
--   but calls are not concurrent. Only a single callback function is
--   called at a given point in time.
data QUICCallbacks
QUICCallbacks :: ([(CryptLevel, ByteString)] -> IO ()) -> (CryptLevel -> IO (Either TLSError ByteString)) -> (Context -> KeyScheduleEvent -> IO ()) -> (Context -> [ExtensionRaw] -> IO ()) -> (Context -> IO ()) -> QUICCallbacks

-- | Called by TLS so that QUIC sends one or more handshake fragments. The
--   content transiting on this API is the plaintext of the fragments and
--   QUIC responsability is to encrypt this payload with the key material
--   given for the specified level and an appropriate encryption scheme.
--   
--   The size of the fragments may exceed QUIC datagram limits so QUIC may
--   break them into smaller fragments.
--   
--   The handshake protocol sometimes combines content at two levels in a
--   single flight. The TLS library does its best to provide this in the
--   same <tt>quicSend</tt> call and with a multi-valued argument. QUIC can
--   then decide how to transmit this optimally.
[quicSend] :: QUICCallbacks -> [(CryptLevel, ByteString)] -> IO ()

-- | Called by TLS to receive from QUIC the next plaintext handshake
--   fragment. The argument specifies with which encryption level the
--   fragment should be decrypted.
--   
--   QUIC may return partial fragments to TLS. TLS will then call
--   <tt>quicRecv</tt> again as long as necessary. Note however that
--   fragments must be returned in the correct sequence, i.e. the order the
--   TLS peer emitted them.
--   
--   The function may return an error to TLS if end of stream is reached or
--   if a protocol error has been received, believing the handshake cannot
--   proceed any longer. If the TLS handshake protocol cannot recover from
--   this error, the failure condition will be reported back to QUIC
--   through the control interface.
[quicRecv] :: QUICCallbacks -> CryptLevel -> IO (Either TLSError ByteString)

-- | Called by TLS when new encryption material is ready to be used in the
--   handshake. The next <a>quicSend</a> or <a>quicRecv</a> may now use the
--   associated encryption level (although the previous level is also
--   possible: directions Send/Recv do not change at the same time).
[quicInstallKeys] :: QUICCallbacks -> Context -> KeyScheduleEvent -> IO ()

-- | Called by TLS when QUIC-specific extensions have been received from
--   the peer.
[quicNotifyExtensions] :: QUICCallbacks -> Context -> [ExtensionRaw] -> IO ()

-- | Called when <a>handshake</a> is done. <a>tlsQUICServer</a> is finished
--   after calling this hook. <a>tlsQUICClient</a> calls <a>recvData</a>
--   after calling this hook to wait for new session tickets.
[quicDone] :: QUICCallbacks -> Context -> IO ()

-- | TLS encryption level.
data CryptLevel

-- | Unprotected traffic
CryptInitial :: CryptLevel

-- | Protected with main secret (TLS &lt; 1.3)
CryptMainSecret :: CryptLevel

-- | Protected with early traffic secret (TLS 1.3)
CryptEarlySecret :: CryptLevel

-- | Protected with handshake traffic secret (TLS 1.3)
CryptHandshakeSecret :: CryptLevel

-- | Protected with application traffic secret (TLS 1.3)
CryptApplicationSecret :: CryptLevel

-- | Argument given to <a>quicInstallKeys</a> when encryption material is
--   available.
data KeyScheduleEvent

-- | Key material and parameters for traffic at 0-RTT level
InstallEarlyKeys :: Maybe EarlySecretInfo -> KeyScheduleEvent

-- | Key material and parameters for traffic at handshake level
InstallHandshakeKeys :: HandshakeSecretInfo -> KeyScheduleEvent

-- | Key material and parameters for traffic at application level
InstallApplicationKeys :: ApplicationSecretInfo -> KeyScheduleEvent

-- | Handshake information generated for traffic at 0-RTT level.
data EarlySecretInfo
EarlySecretInfo :: Cipher -> ClientTrafficSecret EarlySecret -> EarlySecretInfo

-- | Handshake information generated for traffic at handshake level.
data HandshakeSecretInfo
HandshakeSecretInfo :: Cipher -> TrafficSecrets HandshakeSecret -> HandshakeSecretInfo

-- | Handshake information generated for traffic at application level.
newtype ApplicationSecretInfo
ApplicationSecretInfo :: TrafficSecrets ApplicationSecret -> ApplicationSecretInfo

-- | Phantom type indicating early traffic secret.
data EarlySecret

-- | Phantom type indicating handshake traffic secrets.
data HandshakeSecret

-- | Phantom type indicating application traffic secrets.
data ApplicationSecret

-- | Hold both client and server traffic secrets at the same step.
type TrafficSecrets a = (ClientTrafficSecret a, ServerTrafficSecret a)

-- | A server traffic secret, typed with a parameter indicating a step in
--   the TLS key schedule.
newtype ServerTrafficSecret a
ServerTrafficSecret :: ByteString -> ServerTrafficSecret a

-- | A client traffic secret, typed with a parameter indicating a step in
--   the TLS key schedule.
newtype ClientTrafficSecret a
ClientTrafficSecret :: ByteString -> ClientTrafficSecret a

-- | ID of the application-level protocol negotiated between client and
--   server. See values listed in the <a>IANA registry</a>.
type NegotiatedProtocol = ByteString

-- | Type to show which handshake mode is used in TLS 1.3.
data HandshakeMode13

-- | Full handshake is used.
FullHandshake :: HandshakeMode13

-- | Full handshake is used with hello retry request.
HelloRetryRequest :: HandshakeMode13

-- | Server authentication is skipped.
PreSharedKey :: HandshakeMode13

-- | Server authentication is skipped and early data is sent.
RTT0 :: HandshakeMode13

-- | The raw content of a TLS extension.
data ExtensionRaw
ExtensionRaw :: ExtensionID -> ByteString -> ExtensionRaw

-- | Identifier of a TLS extension.
--   <a>http://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.txt</a>
newtype ExtensionID
ExtensionID :: Word16 -> ExtensionID
pattern EID_QuicTransportParameters :: ExtensionID

-- | Can be used by callbacks to signal an unexpected condition. This will
--   then generate an "internal_error" alert in the TLS stack.
errorTLS :: String -> IO a

-- | Return the alert that a TLS endpoint would send to the peer for the
--   specified library error.
errorToAlertDescription :: TLSError -> AlertDescription

-- | Return the message that a TLS endpoint can add to its local log for
--   the specified library error.
errorToAlertMessage :: TLSError -> String
fromAlertDescription :: AlertDescription -> Word8

-- | Decode an alert from the assigned value.
toAlertDescription :: Word8 -> AlertDescription

-- | <tt>HKDF-Expand-Label</tt> function. Returns output keying material of
--   the specified length from the PRK, customized for a TLS label and
--   context.
hkdfExpandLabel :: Hash -> ByteString -> ByteString -> ByteString -> Int -> ByteString

-- | <tt>HKDF-Extract</tt> function. Returns the pseudorandom key (PRK)
--   from salt and input keying material (IKM).
hkdfExtract :: Hash -> ByteString -> ByteString -> ByteString

-- | Digest size in bytes.
hashDigestSize :: Hash -> Int

-- | Max early data size for QUIC.
quicMaxEarlyDataSize :: Int
defaultSupported :: Supported


-- | Native Haskell TLS protocol implementation for servers and clients.
--   
--   This provides a high-level implementation of a sensitive security
--   protocol, eliminating a common set of security issues through the use
--   of the advanced type system, high level constructions and common
--   Haskell features.
--   
--   Currently implement the TLS1.2 and TLS 1.3 protocol, and support RSA
--   and Ephemeral (Elliptic curve and regular) Diffie Hellman key
--   exchanges, and many extensions.
--   
--   The tipical usage is:
--   
--   <pre>
--   socket &lt;- ...
--   ctx &lt;- contextNew socket &lt;params&gt;
--   handshake ctx
--   ... (using recvData and sendData)
--   bye
--   </pre>
module Network.TLS

-- | A TLS Context keep tls specific state, parameters and backend
--   information.
data Context

-- | create a new context using the backend and parameters specified.
contextNew :: (MonadIO m, HasBackend backend, TLSParams params) => backend -> params -> m Context

-- | Handshake for a new TLS connection This is to be called at the
--   beginning of a connection, and during renegotiation. Don't use this
--   function as the acquire resource of <tt>bracket</tt>.
handshake :: MonadIO m => Context -> m ()

-- | sendData sends a bunch of data. It will automatically chunk data to
--   acceptable packet size
sendData :: MonadIO m => Context -> ByteString -> m ()

-- | Get data out of Data packet, and automatically renegotiate if a
--   Handshake ClientHello is received. An empty result means EOF.
recvData :: MonadIO m => Context -> m ByteString

-- | Notify the context that this side wants to close connection. This is
--   important that it is called before closing the handle, otherwise the
--   session might not be resumable (for version &lt; TLS1.2). This doesn't
--   actually close the handle.
--   
--   Proper usage is as follows:
--   
--   <pre>
--   ctx &lt;- contextNew &lt;backend&gt; &lt;params&gt;
--   handshake ctx
--   ...
--   bye
--   </pre>
--   
--   The following code ensures nothing but is no harm.
--   
--   <pre>
--   bracket (contextNew &lt;backend&gt; &lt;params&gt;) bye $ \ctx -&gt; do
--     handshake ctx
--     ...
--   </pre>
bye :: MonadIO m => Context -> m ()
class HasBackend a
initializeBackend :: HasBackend a => a -> IO ()
getBackend :: HasBackend a => a -> Backend

-- | Connection IO backend
data Backend
Backend :: IO () -> IO () -> (ByteString -> IO ()) -> (Int -> IO ByteString) -> Backend

-- | Flush the connection sending buffer, if any.
[backendFlush] :: Backend -> IO ()

-- | Close the connection.
[backendClose] :: Backend -> IO ()

-- | Send a bytestring through the connection.
[backendSend] :: Backend -> ByteString -> IO ()

-- | Receive specified number of bytes from the connection.
[backendRecv] :: Backend -> Int -> IO ByteString
class TLSParams a
data ClientParams

-- | Default value for <a>ClientParams</a>
defaultParamsClient :: HostName -> ByteString -> ClientParams

-- | Define the name of the server, along with an extra service
--   identification blob. this is important that the hostname part is
--   properly filled for security reason, as it allow to properly associate
--   the remote side with the given certificate during a handshake.
--   
--   The extra blob is useful to differentiate services running on the same
--   host, but that might have different certificates given. It's only used
--   as part of the X509 validation infrastructure.
--   
--   This value is typically set by <a>defaultParamsClient</a>.
clientServerIdentification :: ClientParams -> (HostName, ByteString)

-- | Allow the use of the Server Name Indication TLS extension during
--   handshake, which allow the client to specify which host name, it's
--   trying to access. This is useful to distinguish CNAME aliasing (e.g.
--   web virtual host).
--   
--   Default: <a>True</a>
clientUseServerNameIndication :: ClientParams -> Bool

-- | try to establish a connection using this session for TLS 1.2/TLS 1.3.
--   This can be used for TLS 1.3 but for backward compatibility purpose
--   only. Use <tt>clientWantSessionResume13</tt> instead for TLS 1.3.
--   
--   Default: <a>Nothing</a>
clientWantSessionResume :: ClientParams -> Maybe (SessionID, SessionData)

-- | try to establish a connection using one of this sessions especially
--   for TLS 1.3. This take precedence over <a>clientWantSessionResume</a>.
--   For convenience, this can be specified for TLS 1.2 but only the first
--   entry is used.
--   
--   Default: '[]'
clientWantSessionResumeList :: ClientParams -> [(SessionID, SessionData)]

-- | See the default value of <a>Shared</a>.
clientShared :: ClientParams -> Shared

-- | See the default value of <a>ClientHooks</a>.
clientHooks :: ClientParams -> ClientHooks

-- | In this element, you'll need to override the default empty value of of
--   <a>supportedCiphers</a> with a suitable cipherlist.
--   
--   See the default value of <a>Supported</a>.
clientSupported :: ClientParams -> Supported

-- | See the default value of <a>DebugParams</a>.
clientDebug :: ClientParams -> DebugParams

-- | Client tries to send early data in TLS 1.3 via <tt>sendData</tt> if
--   possible. If not accepted by the server, the early data is
--   automatically re-sent.
--   
--   Default: <a>False</a>
clientUseEarlyData :: ClientParams -> Bool
data ServerParams
defaultParamsServer :: ServerParams

-- | Request a certificate from client.
--   
--   Default: <a>False</a>
serverWantClientCert :: ServerParams -> Bool

-- | This is a list of certificates from which the disinguished names are
--   sent in certificate request messages. For TLS1.0, it should not be
--   empty.
--   
--   Default: '[]'
serverCACertificates :: ServerParams -> [SignedCertificate]

-- | Server Optional Diffie Hellman parameters. Setting parameters is
--   necessary for FFDHE key exchange when clients are not compatible with
--   RFC 7919.
--   
--   Value can be one of the standardized groups from module
--   <a>Network.TLS.Extra.FFDHE</a> or custom parameters generated with
--   <a>generateParams</a>.
--   
--   Default: <a>Nothing</a>
serverDHEParams :: ServerParams -> Maybe DHParams

-- | See the default value of <a>ServerHooks</a>.
serverHooks :: ServerParams -> ServerHooks

-- | See the default value of <a>Shared</a>.
serverShared :: ServerParams -> Shared

-- | See the default value of <a>Supported</a>.
serverSupported :: ServerParams -> Supported

-- | See the default value of <a>DebugParams</a>.
serverDebug :: ServerParams -> DebugParams

-- | Server accepts this size of early data in TLS 1.3. 0 (or lower) means
--   that the server does not accept early data.
--   
--   Default: 0
serverEarlyDataSize :: ServerParams -> Int

-- | Lifetime in seconds for session tickets generated by the server.
--   Acceptable value range is 0 to 604800 (7 days).
--   
--   Default: 7200 (2 hours)
serverTicketLifetime :: ServerParams -> Int

-- | Parameters that are common to clients and servers.
data Shared
defaultShared :: Shared

-- | The list of certificates and private keys that a server will use as
--   part of authentication to clients. Actual credentials that are used
--   are selected dynamically from this list based on client capabilities.
--   Additional credentials returned by <a>onServerNameIndication</a> are
--   also considered.
--   
--   When credential list is left empty (the default value), no key
--   exchange can take place.
--   
--   Default: <a>mempty</a>
sharedCredentials :: Shared -> Credentials

-- | Callbacks used by clients and servers in order to resume TLS sessions.
--   The default implementation never resumes sessions. Package
--   <a>tls-session-manager</a> provides an in-memory implementation.
--   
--   Default: <a>noSessionManager</a>
sharedSessionManager :: Shared -> SessionManager

-- | A collection of trust anchors to be used by a client as part of
--   validation of server certificates. This is set as first argument to
--   function <a>onServerCertificate</a>. Package
--   <a>crypton-x509-system</a> gives access to a default certificate store
--   configured in the system.
--   
--   Default: <a>mempty</a>
sharedCAStore :: Shared -> CertificateStore

-- | Callbacks that may be used by a client to cache certificate validation
--   results (positive or negative) and avoid expensive signature check.
--   The default implementation does not have any caching.
--   
--   See the default value of <a>ValidationCache</a>.
sharedValidationCache :: Shared -> ValidationCache

-- | Additional extensions to be sent during the Hello sequence.
--   
--   For a client this is always included in message ClientHello. For a
--   server, this is sent in messages ServerHello or EncryptedExtensions
--   based on the TLS version.
--   
--   Default: <tt>[]</tt>
sharedHelloExtensions :: Shared -> [ExtensionRaw]

-- | Limitation parameters.
sharedLimit :: Shared -> Limit

-- | A set of callbacks run by the clients for various corners of TLS
--   establishment
data ClientHooks
defaultClientHooks :: ClientHooks

-- | Type for <a>onCertificateRequest</a>. This type synonym is to make
--   document readable.
type OnCertificateRequest = ([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO Maybe (CertificateChain, PrivKey)

-- | This action is called when the a certificate request is received from
--   the server. The callback argument is the information from the request.
--   The server, at its discretion, may be willing to continue the
--   handshake without a client certificate. Therefore, the callback is
--   free to return <a>Nothing</a> to indicate that no client certificate
--   should be sent, despite the server's request. In some cases it may be
--   appropriate to get user consent before sending the certificate; the
--   content of the user's certificate may be sensitive and intended only
--   for specific servers.
--   
--   The action should select a certificate chain of one of the given
--   certificate types and one of the certificates in the chain should (if
--   possible) be signed by one of the given distinguished names. Some
--   servers, that don't have a narrow set of preferred issuer CAs, will
--   send an empty <a>DistinguishedName</a> list, rather than send all the
--   names from their trusted CA bundle. If the client does not have a
--   certificate chaining to a matching CA, it may choose a default
--   certificate instead.
--   
--   Each certificate except the last should be signed by the following
--   one. The returned private key must be for the first certificates in
--   the chain. This key will be used to signing the certificate verify
--   message.
--   
--   The public key in the first certificate, and the matching returned
--   private key must be compatible with one of the list of
--   <a>HashAndSignatureAlgorithm</a> value when provided. TLS 1.3 changes
--   the meaning of the list elements, adding explicit code points for each
--   supported pair of hash and signature (public key) algorithms, rather
--   than combining separate codes for the hash and key. For details see
--   <a>RFC 8446</a> section 4.2.3. When no compatible certificate chain is
--   available, return <a>Nothing</a> if it is OK to continue without a
--   client certificate. Returning a non-matching certificate should result
--   in a handshake failure.
--   
--   While the TLS version is not provided to the callback, the content of
--   the <tt>signature_algorithms</tt> list provides a strong hint, since
--   TLS 1.3 servers will generally list RSA pairs with a hash component of
--   <tt>Intrinsic</tt> (<tt>0x08</tt>).
--   
--   Note that is is the responsibility of this action to select a
--   certificate matching one of the requested certificate types (public
--   key algorithms). Returning a non-matching one will lead to handshake
--   failure later.
--   
--   Default: returns <a>Nothing</a> anyway.
onCertificateRequest :: ClientHooks -> OnCertificateRequest

-- | Type for <a>onServerCertificate</a>. This type synonym is to make
--   document readable.
type OnServerCertificate = CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason]

-- | Used by the client to validate the server certificate. The default
--   implementation calls <a>validateDefault</a> which validates according
--   to the default hooks and checks provided by
--   <a>Data.X509.Validation</a>. This can be replaced with a custom
--   validation function using different settings.
--   
--   The function is not expected to verify the key-usage extension of the
--   end-entity certificate, as this depends on the dynamically-selected
--   cipher and this part should not be cached. Key-usage verification is
--   performed by the library internally.
--   
--   Default: <a>validateDefault</a>
onServerCertificate :: ClientHooks -> OnServerCertificate

-- | A utility function for client authentication which can be used
--   <tt>onClientCertificate</tt>.
--   
--   Since: 2.1.7
validateClientCertificate :: CertificateStore -> ValidationCache -> CertificateChain -> IO CertificateUsage

-- | This action is called when the client sends ClientHello to determine
--   ALPN values such as '["h2", "http/1.1"]'.
--   
--   Default: returns <a>Nothing</a>
onSuggestALPN :: ClientHooks -> IO (Maybe [ByteString])

-- | This action is called to validate DHE parameters when the server
--   selected a finite-field group not part of the "Supported Groups
--   Registry" or not part of <a>supportedGroups</a> list.
--   
--   With TLS 1.3 custom groups have been removed from the protocol, so
--   this callback is only used when the version negotiated is 1.2 or
--   below.
--   
--   The default behavior with (dh_p, dh_g, dh_size) and pub as follows:
--   
--   <ol>
--   <li>rejecting if dh_p is even</li>
--   <li>rejecting unless 1 &lt; dh_g &amp;&amp; dh_g &lt; dh_p - 1</li>
--   <li>rejecting unless 1 &lt; dh_p &amp;&amp; pub &lt; dh_p - 1</li>
--   <li>rejecting if dh_size &lt; 1024 (to prevent Logjam attack)</li>
--   </ol>
--   
--   See RFC 7919 section 3.1 for recommandations.
onCustomFFDHEGroup :: ClientHooks -> DHParams -> DHPublic -> IO GroupUsage

-- | When a handshake is done, this hook can check <a>Information</a>.
onServerFinished :: ClientHooks -> Information -> IO ()

-- | A set of callbacks run by the server for various corners of the TLS
--   establishment
data ServerHooks

-- | Default value for <a>ServerHooks</a>
defaultServerHooks :: ServerHooks

-- | This action is called when a client certificate chain is received from
--   the client. When it returns a CertificateUsageReject value, the
--   handshake is aborted.
--   
--   The function is not expected to verify the key-usage extension of the
--   certificate. This verification is performed by the library internally.
--   
--   Default: returns the followings:
--   
--   <pre>
--   CertificateUsageReject (CertificateRejectOther "no client certificates expected")
--   </pre>
onClientCertificate :: ServerHooks -> CertificateChain -> IO CertificateUsage

-- | This action is called when the client certificate cannot be verified.
--   Return <a>True</a> to accept the certificate anyway, or <a>False</a>
--   to fail verification.
--   
--   Default: returns <a>False</a>
onUnverifiedClientCert :: ServerHooks -> IO Bool

-- | Allow the server to choose the cipher relative to the the client
--   version and the client list of ciphers.
--   
--   This could be useful with old clients and as a workaround to the BEAST
--   (where RC4 is sometimes prefered with TLS &lt; 1.1)
--   
--   The client cipher list cannot be empty.
--   
--   Default: taking the head of ciphers.
onCipherChoosing :: ServerHooks -> Version -> [Cipher] -> Cipher

-- | Allow the server to indicate additional credentials to be used
--   depending on the host name indicated by the client.
--   
--   This is most useful for transparent proxies where credentials must be
--   generated on the fly according to the host the client is trying to
--   connect to.
--   
--   Returned credentials may be ignored if a client does not support the
--   signature algorithms used in the certificate chain.
--   
--   Default: returns <a>mempty</a>
onServerNameIndication :: ServerHooks -> Maybe HostName -> IO Credentials

-- | At each new handshake, we call this hook to see if we allow handshake
--   to happens.
--   
--   Default: returns <a>True</a>
onNewHandshake :: ServerHooks -> Measurement -> IO Bool

-- | Allow the server to choose an application layer protocol suggested
--   from the client through the ALPN (Application Layer Protocol
--   Negotiation) extensions. If the server supports no protocols that the
--   client advertises an empty <a>ByteString</a> should be returned.
--   
--   Default: <a>Nothing</a>
onALPNClientSuggest :: ServerHooks -> Maybe ([ByteString] -> IO ByteString)

-- | Allow to modify extensions to be sent in EncryptedExtensions of TLS
--   1.3.
--   
--   Default: <a>return</a>
onEncryptedExtensionsCreating :: ServerHooks -> [ExtensionRaw] -> IO [ExtensionRaw]

-- | record some data about this connection.
data Measurement

-- | number of handshakes on this context
nbHandshakes :: Measurement -> Word32

-- | bytes received since last handshake
bytesReceived :: Measurement -> Word32

-- | bytes sent since last handshake
bytesSent :: Measurement -> Word32

-- | List all the supported algorithms, versions, ciphers, etc supported.
data Supported
defaultSupported :: Supported

-- | Supported versions by this context. On the client side, the highest
--   version will be used to establish the connection. On the server side,
--   the highest version that is less or equal than the client version will
--   be chosen.
--   
--   Versions should be listed in preference order, i.e. higher versions
--   first.
--   
--   Default: <tt>[TLS13,TLS12]</tt>
supportedVersions :: Supported -> [Version]

-- | Supported cipher methods. The default is empty, specify a suitable
--   cipher list. <a>ciphersuite_default</a> is often a good choice.
--   
--   Default: <tt>[]</tt>
supportedCiphers :: Supported -> [Cipher]

-- | Supported compressions methods. By default only the "null" compression
--   is supported, which means no compression will be performed. Allowing
--   other compression method is not advised as it causes a connection
--   failure when TLS 1.3 is negotiated.
--   
--   Default: <tt>[nullCompression]</tt>
supportedCompressions :: Supported -> [Compression]

-- | All supported hash/signature algorithms pair for client certificate
--   verification and server signature in (EC)DHE, ordered by decreasing
--   priority.
--   
--   This list is sent to the peer as part of the "signature_algorithms"
--   extension. It is used to restrict accepted signatures received from
--   the peer at TLS level (not in X.509 certificates), but only when the
--   TLS version is 1.2 or above. In order to disable SHA-1 one must then
--   also disable earlier protocol versions in <a>supportedVersions</a>.
--   
--   The list also impacts the selection of possible algorithms when
--   generating signatures.
--   
--   Note: with TLS 1.3 some algorithms have been deprecated and will not
--   be used even when listed in the parameter: MD5, SHA-1, SHA-224, RSA
--   PKCS#1, DSA.
--   
--   Default:
--   
--   <pre>
--   [ (HashIntrinsic,     SignatureEd448)
--   , (HashIntrinsic,     SignatureEd25519)
--   , (Struct.HashSHA256, SignatureECDSA)
--   , (Struct.HashSHA384, SignatureECDSA)
--   , (Struct.HashSHA512, SignatureECDSA)
--   , (HashIntrinsic,     SignatureRSApssRSAeSHA512)
--   , (HashIntrinsic,     SignatureRSApssRSAeSHA384)
--   , (HashIntrinsic,     SignatureRSApssRSAeSHA256)
--   , (Struct.HashSHA512, SignatureRSA)
--   , (Struct.HashSHA384, SignatureRSA)
--   , (Struct.HashSHA256, SignatureRSA)
--   , (Struct.HashSHA1,   SignatureRSA)
--   , (Struct.HashSHA1,   SignatureDSA)
--   ]
--   </pre>
supportedHashSignatures :: Supported -> [HashAndSignatureAlgorithm]

-- | Secure renegotiation defined in RFC5746. If <a>True</a>, clients send
--   the renegotiation_info extension. If <a>True</a>, servers handle the
--   extension or the renegotiation SCSV then send the renegotiation_info
--   extension.
--   
--   Default: <a>True</a>
supportedSecureRenegotiation :: Supported -> Bool

-- | If <a>True</a>, renegotiation is allowed from the client side. This is
--   vulnerable to DOS attacks. If <a>False</a>, renegotiation is allowed
--   only from the server side via HelloRequest.
--   
--   Default: <a>False</a>
supportedClientInitiatedRenegotiation :: Supported -> Bool

-- | The mode regarding extended main secret. Enabling this extension
--   provides better security for TLS versions 1.2. TLS 1.3 provides the
--   security properties natively and does not need the extension.
--   
--   By default the extension is <a>RequireEMS</a>. So, the handshake will
--   fail when the peer does not support the extension.
--   
--   Default: <a>RequireEMS</a>
supportedExtendedMainSecret :: Supported -> EMSMode

-- | Set if we support session.
--   
--   Default: <a>True</a>
supportedSession :: Supported -> Bool

-- | Support for fallback SCSV defined in RFC7507. If <a>True</a>, servers
--   reject handshakes which suggest a lower protocol than the highest
--   protocol supported.
--   
--   Default: <a>True</a>
supportedFallbackScsv :: Supported -> Bool

-- | In ver &lt;= TLS1.0, block ciphers using CBC are using CBC residue as
--   IV, which can be guessed by an attacker. Hence, an empty packet is
--   normally sent before a normal data packet, to prevent guessability.
--   Some Microsoft TLS-based protocol implementations, however, consider
--   these empty packets as a protocol violation and disconnect. If this
--   parameter is <a>False</a>, empty packets will never be added, which is
--   less secure, but might help in rare cases.
--   
--   Default: <a>True</a>
supportedEmptyPacket :: Supported -> Bool

-- | A list of supported elliptic curves and finite-field groups in the
--   preferred order.
--   
--   The list is sent to the server as part of the "supported_groups"
--   extension. It is used in both clients and servers to restrict accepted
--   groups in DH key exchange. Up until TLS v1.2, it is also used by a
--   client to restrict accepted elliptic curves in ECDSA signatures.
--   
--   The default value includes all groups with security strength of 128
--   bits or more.
--   
--   Default:
--   <tt>[X25519,X448,P256,FFDHE2048,FFDHE3072,FFDHE4096,P384,FFDHE6144,FFDHE8192,P521]</tt>
supportedGroups :: Supported -> [Group]

-- | All settings should not be used in production
data DebugParams

-- | Default value for <a>DebugParams</a>
defaultDebugParams :: DebugParams

-- | Disable the true randomness in favor of deterministic seed that will
--   produce a deterministic random from. This is useful for tests and
--   debugging purpose. Do not use in production
--   
--   Default: <a>Nothing</a>
debugSeed :: DebugParams -> Maybe Seed

-- | Add a way to print the seed that was randomly generated. re-using the
--   same seed will reproduce the same randomness with <a>debugSeed</a>
--   
--   Default: no printing
debugPrintSeed :: DebugParams -> Seed -> IO ()

-- | Force to choose this version in the server side.
--   
--   Default: <a>Nothing</a>
debugVersionForced :: DebugParams -> Maybe Version

-- | Printing main keys.
--   
--   Default: no printing
debugKeyLogger :: DebugParams -> String -> IO ()

-- | Limitations for security.
data Limit

-- | Default value for <a>Limit</a>.
defaultLimit :: Limit

-- | The limit to accept the number of each handshake message. For
--   instance, a nasty client may send many fragments of client
--   certificate.
--   
--   Default: 32
limitHandshakeFragment :: Limit -> Int

-- | Record size limit defined in RFC 8449.
--   
--   If <a>Nothing</a>, the "record_size_limit" extension is not used.
--   
--   In the case of <a>Just</a>: A client sends the "record_size_limit"
--   extension with this value to the server. A server sends back this
--   extension with its own value if a client sends the extension. When
--   negotiated, both my limit and peer's limit are enabled for protected
--   communication.
--   
--   Default: Nothing
limitRecordSize :: Limit -> Maybe Int
newtype Credentials
Credentials :: [Credential] -> Credentials
type Credential = (CertificateChain, PrivKey)

-- | try to create a new credential object from a public certificate and
--   the associated private key that are stored on the filesystem in PEM
--   format.
credentialLoadX509 :: FilePath -> FilePath -> IO (Either String Credential)

-- | similar to <a>credentialLoadX509</a> but take the certificate and
--   private key from memory instead of from the filesystem.
credentialLoadX509FromMemory :: ByteString -> ByteString -> Either String Credential

-- | similar to <a>credentialLoadX509</a> but also allow specifying chain
--   certificates.
credentialLoadX509Chain :: FilePath -> [FilePath] -> FilePath -> IO (Either String Credential)

-- | similar to <a>credentialLoadX509FromMemory</a> but also allow
--   specifying chain certificates.
credentialLoadX509ChainFromMemory :: ByteString -> [ByteString] -> ByteString -> Either String Credential

-- | A session manager. In the server side, all fields are used. In the
--   client side, only <a>sessionEstablish</a> is used.
data SessionManager

-- | The session manager to do nothing.
noSessionManager :: SessionManager

-- | Used on TLS 1.2/1.3 servers to lookup <a>SessionData</a> with
--   <a>SessionID</a> or to decrypt <a>Ticket</a> to get
--   <a>SessionData</a>.
sessionResume :: SessionManager -> SessionIDorTicket -> IO (Maybe SessionData)

-- | Used for 0RTT on TLS 1.3 servers to lookup <a>SessionData</a> with
--   <a>SessionID</a> or to decrypt <a>Ticket</a> to get
--   <a>SessionData</a>.
sessionResumeOnlyOnce :: SessionManager -> SessionIDorTicket -> IO (Maybe SessionData)

-- | Used on TLS 1.2/1.3 servers to store <a>SessionData</a> with
--   <a>SessionID</a> or to encrypt <a>SessionData</a> to get <a>Ticket</a>
--   ignoring <a>SessionID</a>. Used on TLS 1.2/1.3 clients to store
--   <a>SessionData</a> with <a>SessionIDorTicket</a> and then return
--   <a>Nothing</a>. For clients, only this field should be set with
--   <a>noSessionManager</a>.
sessionEstablish :: SessionManager -> SessionIDorTicket -> SessionData -> IO (Maybe Ticket)

-- | Used TLS 1.2 servers to delete <a>SessionData</a> with
--   <a>SessionID</a> on errors.
sessionInvalidate :: SessionManager -> SessionIDorTicket -> IO ()

-- | Used on TLS 1.2 servers to decide to use <a>SessionID</a> or
--   <a>Ticket</a>. Note that <a>SessionID</a> and <a>Ticket</a> are
--   integrated as identity in TLS 1.3.
sessionUseTicket :: SessionManager -> Bool

-- | A session ID
type SessionID = ByteString

-- | Identity
type SessionIDorTicket = ByteString

-- | Encrypted session ticket (encrypt(encode <a>SessionData</a>)).
type Ticket = ByteString

-- | Session data to resume
data SessionData
sessionVersion :: SessionData -> Version
sessionCipher :: SessionData -> CipherID
sessionCompression :: SessionData -> CompressionID
sessionClientSNI :: SessionData -> Maybe HostName
sessionSecret :: SessionData -> ByteString
sessionGroup :: SessionData -> Maybe Group
sessionTicketInfo :: SessionData -> Maybe TLS13TicketInfo
sessionALPN :: SessionData -> Maybe ByteString
sessionMaxEarlyDataSize :: SessionData -> Int
sessionFlags :: SessionData -> [SessionFlag]

-- | Some session flags
data SessionFlag

-- | Session created with Extended Main Secret
SessionEMS :: SessionFlag
data TLS13TicketInfo
is0RTTPossible :: SessionData -> Bool
data ValidationCache
ValidationCache :: ValidationCacheQueryCallback -> ValidationCacheAddCallback -> ValidationCache
[cacheQuery] :: ValidationCache -> ValidationCacheQueryCallback
[cacheAdd] :: ValidationCache -> ValidationCacheAddCallback
defaultValidationCache :: ValidationCache
type ValidationCacheQueryCallback = ServiceID -> Fingerprint -> Certificate -> IO ValidationCacheResult
type ValidationCacheAddCallback = ServiceID -> Fingerprint -> Certificate -> IO ()
data ValidationCacheResult
ValidationCachePass :: ValidationCacheResult
ValidationCacheDenied :: String -> ValidationCacheResult
ValidationCacheUnknown :: ValidationCacheResult
exceptionValidationCache :: [(ServiceID, Fingerprint)] -> ValidationCache

-- | Versions known to TLS
newtype Version
Version :: Word16 -> Version
pattern TLS12 :: Version
pattern TLS13 :: Version
pattern SSL2 :: Version
pattern SSL3 :: Version
pattern TLS10 :: Version
pattern TLS11 :: Version

-- | every compression need to be wrapped in this, to fit in structure
data Compression
Compression :: a -> Compression

-- | default null compression
nullCompression :: Compression
type HashAndSignatureAlgorithm = (HashAlgorithm, SignatureAlgorithm)
supportedSignatureSchemes :: [HashAndSignatureAlgorithm]
newtype HashAlgorithm
HashAlgorithm :: Word8 -> HashAlgorithm
[fromHashAlgorithm] :: HashAlgorithm -> Word8
pattern HashNone :: HashAlgorithm
pattern HashMD5 :: HashAlgorithm
pattern HashSHA1 :: HashAlgorithm
pattern HashSHA224 :: HashAlgorithm
pattern HashSHA256 :: HashAlgorithm
pattern HashSHA384 :: HashAlgorithm
pattern HashSHA512 :: HashAlgorithm
pattern HashIntrinsic :: HashAlgorithm
newtype SignatureAlgorithm
SignatureAlgorithm :: Word8 -> SignatureAlgorithm
[fromSignatureAlgorithm] :: SignatureAlgorithm -> Word8
pattern SignatureAnonymous :: SignatureAlgorithm
pattern SignatureRSA :: SignatureAlgorithm
pattern SignatureDSA :: SignatureAlgorithm
pattern SignatureECDSA :: SignatureAlgorithm
pattern SignatureRSApssRSAeSHA256 :: SignatureAlgorithm
pattern SignatureRSApssRSAeSHA384 :: SignatureAlgorithm
pattern SignatureRSApssRSAeSHA512 :: SignatureAlgorithm
pattern SignatureEd25519 :: SignatureAlgorithm
pattern SignatureEd448 :: SignatureAlgorithm
pattern SignatureRSApsspssSHA256 :: SignatureAlgorithm
pattern SignatureRSApsspssSHA384 :: SignatureAlgorithm
pattern SignatureRSApsspssSHA512 :: SignatureAlgorithm
pattern SignatureBrainpoolP256 :: SignatureAlgorithm
pattern SignatureBrainpoolP384 :: SignatureAlgorithm
pattern SignatureBrainpoolP512 :: SignatureAlgorithm
newtype Group
Group :: Word16 -> Group
pattern P256 :: Group
pattern P384 :: Group
pattern P521 :: Group
pattern X25519 :: Group
pattern X448 :: Group
pattern FFDHE2048 :: Group
pattern FFDHE3072 :: Group
pattern FFDHE4096 :: Group
pattern FFDHE6144 :: Group
pattern FFDHE8192 :: Group
supportedNamedGroups :: [Group]

-- | Client or server policy regarding Extended Main Secret
data EMSMode

-- | Extended Main Secret is not used
NoEMS :: EMSMode

-- | Extended Main Secret is allowed
AllowEMS :: EMSMode

-- | Extended Main Secret is required
RequireEMS :: EMSMode
type DHParams = Params
type DHPublic = PublicNumber

-- | Group usage callback possible return values.
data GroupUsage

-- | usage of group accepted
GroupUsageValid :: GroupUsage

-- | usage of group provides insufficient security
GroupUsageInsecure :: GroupUsage

-- | usage of group rejected for other reason (specified as string)
GroupUsageUnsupported :: String -> GroupUsage

-- | usage of group with an invalid public value
GroupUsageInvalidPublic :: GroupUsage

-- | Certificate Usage callback possible returns values.
data CertificateUsage

-- | usage of certificate accepted
CertificateUsageAccept :: CertificateUsage

-- | usage of certificate rejected
CertificateUsageReject :: CertificateRejectReason -> CertificateUsage

-- | Certificate and Chain rejection reason
data CertificateRejectReason
CertificateRejectExpired :: CertificateRejectReason
CertificateRejectRevoked :: CertificateRejectReason
CertificateRejectUnknownCA :: CertificateRejectReason
CertificateRejectAbsent :: CertificateRejectReason
CertificateRejectOther :: String -> CertificateRejectReason

-- | Some of the IANA registered code points for <a>CertificateType</a> are
--   not currently supported by the library. Nor should they be, they're
--   are either unwise, obsolete or both. There's no point in conveying
--   these to the user in the client certificate request callback. The
--   request callback will be filtered to exclude unsupported values. If
--   the user cannot find a certificate for a supported code point, we'll
--   go ahead without a client certificate and hope for the best, unless
--   the user's callback decides to throw an exception.
newtype CertificateType
CertificateType :: Word8 -> CertificateType
[fromCertificateType] :: CertificateType -> Word8

-- | TLS10 and up, RFC5246
pattern CertificateType_RSA_Sign :: CertificateType

-- | TLS10 and up, RFC5246
pattern CertificateType_DSA_Sign :: CertificateType

-- | TLS10 and up, RFC8422
pattern CertificateType_ECDSA_Sign :: CertificateType
pattern CertificateType_Ed25519_Sign :: CertificateType
pattern CertificateType_Ed448_Sign :: CertificateType
newtype CertificateChain
CertificateChain :: [SignedExact Certificate] -> CertificateChain
type HostName = String
data MaxFragmentEnum
MaxFragment512 :: MaxFragmentEnum
MaxFragment1024 :: MaxFragmentEnum
MaxFragment2048 :: MaxFragmentEnum
MaxFragment4096 :: MaxFragmentEnum

-- | return the backend object associated with this context
ctxBackend :: Context -> Backend

-- | A shortcut for 'backendFlush . ctxBackend'.
contextFlush :: Context -> IO ()

-- | A shortcut for 'backendClose . ctxBackend'.
contextClose :: Context -> IO ()

-- | Information related to a running context, e.g. current cipher
data Information

-- | Information about the current context
contextGetInformation :: Context -> IO (Maybe Information)
infoVersion :: Information -> Version
infoCipher :: Information -> Cipher
infoCompression :: Information -> Compression
infoMainSecret :: Information -> Maybe ByteString
infoExtendedMainSecret :: Information -> Bool
infoClientRandom :: Information -> Maybe ClientRandom
infoServerRandom :: Information -> Maybe ServerRandom
infoSupportedGroup :: Information -> Maybe Group
infoTLS12Resumption :: Information -> Bool
infoTLS13HandshakeMode :: Information -> Maybe HandshakeMode13
infoIsEarlyDataAccepted :: Information -> Bool
data ClientRandom
data ServerRandom
unClientRandom :: ClientRandom -> ByteString
unServerRandom :: ServerRandom -> ByteString

-- | Type to show which handshake mode is used in TLS 1.3.
data HandshakeMode13

-- | Full handshake is used.
FullHandshake :: HandshakeMode13

-- | Full handshake is used with hello retry request.
HelloRetryRequest :: HandshakeMode13

-- | Server authentication is skipped.
PreSharedKey :: HandshakeMode13

-- | Server authentication is skipped and early data is sent.
RTT0 :: HandshakeMode13

-- | Getting certificates from a client, if any. Note that the certificates
--   are not sent by a client on resumption even if client authentication
--   is required. So, this API would be replaced by the one which can treat
--   both cases of full-negotiation and resumption.
getClientCertificateChain :: Context -> IO (Maybe CertificateChain)

-- | If the ALPN extensions have been used, this will return get the
--   protocol agreed upon.
getNegotiatedProtocol :: MonadIO m => Context -> m (Maybe ByteString)

-- | If the Server Name Indication extension has been used, return the
--   hostname specified by the client.
getClientSNI :: MonadIO m => Context -> m (Maybe HostName)

-- | Updating appication traffic secrets for TLS 1.3. If this API is called
--   for TLS 1.3, <a>True</a> is returned. Otherwise, <a>False</a> is
--   returned.
updateKey :: MonadIO m => Context -> KeyUpdateRequest -> m Bool

-- | How to update keys in TLS 1.3
data KeyUpdateRequest

-- | Unidirectional key update
OneWay :: KeyUpdateRequest

-- | Bidirectional key update (normal case)
TwoWay :: KeyUpdateRequest

-- | Post-handshake certificate request with TLS 1.3. Returns <a>True</a>
--   if the request was possible, i.e. if TLS 1.3 is used and the remote
--   client supports post-handshake authentication.
requestCertificate :: Context -> IO Bool

-- | Getting the "tls-unique" channel binding for TLS 1.2 (RFC5929). For
--   TLS 1.3, <a>Nothing</a> is returned.
--   <a>supportedExtendedMainSecret</a> must be <a>RequireEMS</a> But in
--   general, it is highly recommended to upgrade to TLS 1.3 and use the
--   "tls-exporter" channel binding via <a>getTLSExporter</a>.
getTLSUnique :: Context -> IO (Maybe ByteString)

-- | Getting the "tls-exporter" channel binding for TLS 1.3 (RFC9266). For
--   TLS 1.2, <a>Nothing</a> is returned.
getTLSExporter :: Context -> IO (Maybe ByteString)

-- | Getting the "tls-server-end-point" channel binding for TLS 1.2
--   (RFC5929). For 1.3, there is no specifications for how to create it.
--   In this implementation, a certificate chain without extensions is
--   hashed like TLS 1.2.
getTLSServerEndPoint :: Context -> IO (Maybe ByteString)

-- | Getting TLS Finished sent to peer.

-- | <i>Deprecated: Use getTLSUnique instead</i>
getFinished :: Context -> IO (Maybe VerifyData)

-- | Getting TLS Finished received from peer.

-- | <i>Deprecated: Use getTLSUnique instead</i>
getPeerFinished :: Context -> IO (Maybe VerifyData)

-- | A collection of hooks actions.
data Hooks
defaultHooks :: Hooks

-- | called at each handshake message received
hookRecvHandshake :: Hooks -> Handshake -> IO Handshake

-- | called at each handshake message received for TLS 1.3
hookRecvHandshake13 :: Hooks -> Handshake13 -> IO Handshake13

-- | called at each certificate chain message received
hookRecvCertificates :: Hooks -> CertificateChain -> IO ()

-- | hooks on IO and packets, receiving and sending.
hookLogging :: Hooks -> Logging
contextModifyHooks :: Context -> (Hooks -> Hooks) -> IO ()
data Handshake
contextHookSetHandshakeRecv :: Context -> (Handshake -> IO Handshake) -> IO ()
data Handshake13
contextHookSetHandshake13Recv :: Context -> (Handshake13 -> IO Handshake13) -> IO ()
contextHookSetCertificateRecv :: Context -> (CertificateChain -> IO ()) -> IO ()

-- | Hooks for logging
--   
--   This is called when sending and receiving packets and IO
data Logging
defaultLogging :: Logging
loggingPacketSent :: Logging -> String -> IO ()
loggingPacketRecv :: Logging -> String -> IO ()
loggingIOSent :: Logging -> ByteString -> IO ()
loggingIORecv :: Logging -> Header -> ByteString -> IO ()
data Header
Header :: ProtocolType -> Version -> Word16 -> Header
newtype ProtocolType
ProtocolType :: Word8 -> ProtocolType
[fromProtocolType] :: ProtocolType -> Word8
pattern ProtocolType_ChangeCipherSpec :: ProtocolType
pattern ProtocolType_Alert :: ProtocolType
pattern ProtocolType_Handshake :: ProtocolType
pattern ProtocolType_AppData :: ProtocolType
contextHookSetLogging :: Context -> Logging -> IO ()

-- | TLSError that might be returned through the TLS stack.
--   
--   Prior to version 1.8.0, this type had an <tt>Exception</tt> instance.
--   In version 1.8.0, this instance was removed, and functions in this
--   library now only throw <a>TLSException</a>.
data TLSError

-- | mainly for instance of Error
Error_Misc :: String -> TLSError

-- | A fatal error condition was encountered at a low level. The elements
--   of the tuple give (freeform text description, structured error
--   description).
Error_Protocol :: String -> AlertDescription -> TLSError

-- | A non-fatal error condition was encountered at a low level at a low
--   level. The elements of the tuple give (freeform text description,
--   structured error description).
Error_Protocol_Warning :: String -> AlertDescription -> TLSError
Error_Certificate :: String -> TLSError

-- | handshake policy failed.
Error_HandshakePolicy :: String -> TLSError
Error_EOF :: TLSError
Error_Packet :: String -> TLSError
Error_Packet_unexpected :: String -> String -> TLSError
Error_Packet_Parsing :: String -> TLSError
Error_TCP_Terminate :: TLSError
data KxError
RSAError :: Error -> KxError
KxUnsupported :: KxError
newtype AlertDescription
AlertDescription :: Word8 -> AlertDescription
[fromAlertDescription] :: AlertDescription -> Word8
pattern CloseNotify :: AlertDescription
pattern UnexpectedMessage :: AlertDescription
pattern BadRecordMac :: AlertDescription
pattern DecryptionFailed :: AlertDescription
pattern RecordOverflow :: AlertDescription
pattern DecompressionFailure :: AlertDescription
pattern HandshakeFailure :: AlertDescription
pattern BadCertificate :: AlertDescription
pattern UnsupportedCertificate :: AlertDescription
pattern CertificateRevoked :: AlertDescription
pattern CertificateExpired :: AlertDescription
pattern CertificateUnknown :: AlertDescription
pattern IllegalParameter :: AlertDescription
pattern UnknownCa :: AlertDescription
pattern AccessDenied :: AlertDescription
pattern DecodeError :: AlertDescription
pattern DecryptError :: AlertDescription
pattern ExportRestriction :: AlertDescription
pattern ProtocolVersion :: AlertDescription
pattern InsufficientSecurity :: AlertDescription
pattern InternalError :: AlertDescription
pattern InappropriateFallback :: AlertDescription
pattern UserCanceled :: AlertDescription
pattern NoRenegotiation :: AlertDescription
pattern MissingExtension :: AlertDescription
pattern UnsupportedExtension :: AlertDescription
pattern CertificateUnobtainable :: AlertDescription
pattern UnrecognizedName :: AlertDescription
pattern BadCertificateStatusResponse :: AlertDescription
pattern BadCertificateHashValue :: AlertDescription
pattern UnknownPskIdentity :: AlertDescription
pattern CertificateRequired :: AlertDescription
pattern NoApplicationProtocol :: AlertDescription

-- | TLS Exceptions. Some of the data constructors indicate incorrect use
--   of the library, and the documentation for those data constructors
--   calls this out. The others wrap <a>TLSError</a> with some kind of
--   context to explain when the exception occurred.
data TLSException

-- | Early termination exception with the reason and the error associated
Terminated :: Bool -> String -> TLSError -> TLSException

-- | Handshake failed for the reason attached.
HandshakeFailed :: TLSError -> TLSException

-- | Failure occurred while sending or receiving data after the TLS
--   handshake succeeded.
PostHandshake :: TLSError -> TLSException

-- | Lifts a <a>TLSError</a> into <a>TLSException</a> without provided any
--   context around when the error happened.
Uncontextualized :: TLSError -> TLSException

-- | Usage error when the connection has not been established and the user
--   is trying to send or receive data. Indicates that this library has
--   been used incorrectly.
ConnectionNotEstablished :: TLSException

-- | Expected that a TLS handshake had already taken place, but no TLS
--   handshake had occurred. Indicates that this library has been used
--   incorrectly.
MissingHandshake :: TLSException

-- | supported compression algorithms need to be part of this class
class CompressionC a
compressionCID :: CompressionC a => a -> CompressionID
compressionCDeflate :: CompressionC a => a -> ByteString -> (a, ByteString)
compressionCInflate :: CompressionC a => a -> ByteString -> (a, ByteString)

-- | Compression identification
type CompressionID = Word8
data PubKey
PubKeyRSA :: PublicKey -> PubKey
PubKeyDSA :: PublicKey -> PubKey
PubKeyDH :: (Integer, Integer, Integer, Maybe Integer, ([Word8], Integer)) -> PubKey
PubKeyEC :: PubKeyEC -> PubKey
PubKeyX25519 :: PublicKey -> PubKey
PubKeyX448 :: PublicKey -> PubKey
PubKeyEd25519 :: PublicKey -> PubKey
PubKeyEd448 :: PublicKey -> PubKey
PubKeyUnknown :: OID -> ByteString -> PubKey
data PrivKey
PrivKeyRSA :: PrivateKey -> PrivKey
PrivKeyDSA :: PrivateKey -> PrivKey
PrivKeyEC :: PrivKeyEC -> PrivKey
PrivKeyX25519 :: SecretKey -> PrivKey
PrivKeyX448 :: SecretKey -> PrivKey
PrivKeyEd25519 :: SecretKey -> PrivKey
PrivKeyEd448 :: SecretKey -> PrivKey

-- | Cipher algorithm
data Cipher
Cipher :: CipherID -> String -> Hash -> Bulk -> CipherKeyExchangeType -> Maybe Version -> Maybe Hash -> Cipher
[cipherID] :: Cipher -> CipherID
[cipherName] :: Cipher -> String
[cipherHash] :: Cipher -> Hash
[cipherBulk] :: Cipher -> Bulk
[cipherKeyExchange] :: Cipher -> CipherKeyExchangeType
[cipherMinVer] :: Cipher -> Maybe Version
[cipherPRFHash] :: Cipher -> Maybe Hash
data CipherKeyExchangeType
CipherKeyExchange_RSA :: CipherKeyExchangeType
CipherKeyExchange_DH_Anon :: CipherKeyExchangeType
CipherKeyExchange_DHE_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDHE_RSA :: CipherKeyExchangeType
CipherKeyExchange_DHE_DSA :: CipherKeyExchangeType
CipherKeyExchange_DH_DSA :: CipherKeyExchangeType
CipherKeyExchange_DH_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDH_ECDSA :: CipherKeyExchangeType
CipherKeyExchange_ECDH_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDHE_ECDSA :: CipherKeyExchangeType
CipherKeyExchange_TLS13 :: CipherKeyExchangeType
data Bulk
Bulk :: String -> Int -> Int -> Int -> Int -> Int -> BulkFunctions -> Bulk
[bulkName] :: Bulk -> String
[bulkKeySize] :: Bulk -> Int
[bulkIVSize] :: Bulk -> Int
[bulkExplicitIV] :: Bulk -> Int
[bulkAuthTagLen] :: Bulk -> Int
[bulkBlockSize] :: Bulk -> Int
[bulkF] :: Bulk -> BulkFunctions
data BulkFunctions
BulkBlockF :: (BulkDirection -> BulkKey -> BulkBlock) -> BulkFunctions
BulkStreamF :: (BulkDirection -> BulkKey -> BulkStream) -> BulkFunctions
BulkAeadF :: (BulkDirection -> BulkKey -> BulkAEAD) -> BulkFunctions
data BulkDirection
BulkEncrypt :: BulkDirection
BulkDecrypt :: BulkDirection
data BulkState
BulkStateStream :: BulkStream -> BulkState
BulkStateBlock :: BulkBlock -> BulkState
BulkStateAEAD :: BulkAEAD -> BulkState
BulkStateUninitialized :: BulkState
newtype BulkStream
BulkStream :: (ByteString -> (ByteString, BulkStream)) -> BulkStream
type BulkBlock = BulkIV -> ByteString -> (ByteString, BulkIV)
type BulkAEAD = BulkNonce -> ByteString -> BulkAdditionalData -> (ByteString, AuthTag)
bulkInit :: Bulk -> BulkDirection -> BulkKey -> BulkState
data Hash
MD5 :: Hash
SHA1 :: Hash
SHA224 :: Hash
SHA256 :: Hash
SHA384 :: Hash
SHA512 :: Hash
SHA1_MD5 :: Hash

-- | Cipher identification
type CipherID = Word16
cipherKeyBlockSize :: Cipher -> Int
type BulkKey = ByteString
type BulkIV = ByteString
type BulkNonce = ByteString
type BulkAdditionalData = ByteString

-- | Check if a specific <a>Cipher</a> is allowed to be used with the
--   version specified
cipherAllowedForVersion :: Version -> Cipher -> Bool
hasMAC :: BulkFunctions -> Bool
hasRecordIV :: BulkFunctions -> Bool
elemCipher :: [CipherId] -> Cipher -> Bool
intersectCiphers :: [CipherId] -> [Cipher] -> [Cipher]
findCipher :: CipherID -> [Cipher] -> Maybe Cipher

-- | same as recvData but returns a lazy bytestring.

-- | <i>Deprecated: use recvData that returns strict bytestring</i>
recvData' :: MonadIO m => Context -> m ByteString

-- | <i>Deprecated: Use Data.ByteString.Bytestring instead of Bytes.</i>
type Bytes = ByteString
data ValidationChecks
ValidationChecks :: Bool -> Maybe DateTime -> Bool -> Bool -> Bool -> Bool -> [ExtKeyUsageFlag] -> [ExtKeyUsagePurpose] -> Bool -> ValidationChecks
[checkTimeValidity] :: ValidationChecks -> Bool
[checkAtTime] :: ValidationChecks -> Maybe DateTime
[checkStrictOrdering] :: ValidationChecks -> Bool
[checkCAConstraints] :: ValidationChecks -> Bool
[checkExhaustive] :: ValidationChecks -> Bool
[checkLeafV3] :: ValidationChecks -> Bool
[checkLeafKeyUsage] :: ValidationChecks -> [ExtKeyUsageFlag]
[checkLeafKeyPurpose] :: ValidationChecks -> [ExtKeyUsagePurpose]
[checkFQHN] :: ValidationChecks -> Bool
data ValidationHooks
ValidationHooks :: (DistinguishedName -> Certificate -> Bool) -> (DateTime -> Certificate -> [FailedReason]) -> (HostName -> Certificate -> [FailedReason]) -> ([FailedReason] -> [FailedReason]) -> ValidationHooks
[hookMatchSubjectIssuer] :: ValidationHooks -> DistinguishedName -> Certificate -> Bool
[hookValidateTime] :: ValidationHooks -> DateTime -> Certificate -> [FailedReason]
[hookValidateName] :: ValidationHooks -> HostName -> Certificate -> [FailedReason]
[hookFilterReason] :: ValidationHooks -> [FailedReason] -> [FailedReason]

-- | Default: <a>Nothing</a>

-- | <i>Deprecated: UseMaxFragmentLength is deprecated</i>
clientUseMaxFragmentLength :: ClientParams -> Maybe MaxFragmentEnum
