libghc-tls-doc 1.3.8-3 / usr / share / doc / libghc-tls-doc / html / tls.txt

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


-- | TLS/SSL protocol native implementation (Server and Client)
--   
--   Native Haskell TLS and SSL protocol implementation for server and
--   client.
--   
--   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 SSL3.0, TLS1.0, TLS1.1 and TLS1.2 protocol,
--   and support RSA and Ephemeral (Elliptic curve and regular) Diffie
--   Hellman key exchanges, and many extensions.
--   
--   Some debug tools linked with tls, are available through the
--   <a>http://hackage.haskell.org/package/tls-debug/</a>.
@package tls
@version 1.3.8


module Network.TLS
data ClientParams
ClientParams :: Maybe MaxFragmentEnum -> (HostName, Bytes) -> Bool -> Maybe (SessionID, SessionData) -> Shared -> ClientHooks -> Supported -> DebugParams -> ClientParams
[clientUseMaxFragmentLength] :: ClientParams -> Maybe MaxFragmentEnum

-- | 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.
[clientServerIdentification] :: ClientParams -> (HostName, Bytes)

-- | 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).
[clientUseServerNameIndication] :: ClientParams -> Bool

-- | try to establish a connection using this session.
[clientWantSessionResume] :: ClientParams -> Maybe (SessionID, SessionData)
[clientShared] :: ClientParams -> Shared
[clientHooks] :: ClientParams -> ClientHooks
[clientSupported] :: ClientParams -> Supported
[clientDebug] :: ClientParams -> DebugParams
data ServerParams
ServerParams :: Bool -> [SignedCertificate] -> Maybe DHParams -> Shared -> ServerHooks -> Supported -> DebugParams -> ServerParams

-- | request a certificate from client.
[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.
[serverCACertificates] :: ServerParams -> [SignedCertificate]

-- | Server Optional Diffie Hellman parameters. If this value is not
--   properly set, no Diffie Hellman key exchange will take place.
[serverDHEParams] :: ServerParams -> Maybe DHParams
[serverShared] :: ServerParams -> Shared
[serverHooks] :: ServerParams -> ServerHooks
[serverSupported] :: ServerParams -> Supported
[serverDebug] :: ServerParams -> DebugParams

-- | All settings should not be used in production
data DebugParams
DebugParams :: Maybe Seed -> (Seed -> IO ()) -> 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
[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>
[debugPrintSeed] :: DebugParams -> Seed -> IO ()

-- | A set of callbacks run by the clients for various corners of TLS
--   establishment
data ClientHooks
ClientHooks :: (([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO (Maybe (CertificateChain, PrivKey))) -> Maybe ([ByteString] -> IO ByteString) -> (CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason]) -> IO (Maybe [ByteString]) -> ClientHooks

-- | This action is called when the server sends a certificate request. The
--   parameter is the information from the request. The action should
--   select a certificate chain of one of the given certificate types where
--   the last certificate in the chain should be signed by one of the given
--   distinguished names. Each certificate should be signed by the
--   following one, except for the last. At least the first of the
--   certificates in the chain must have a corresponding private key,
--   because that is used for signing the certificate verify message.
--   
--   Note that is is the responsibility of this action to select a
--   certificate matching one of the requested certificate types. Returning
--   a non-matching one will lead to handshake failure later.
--   
--   Returning a certificate chain not matching the distinguished names may
--   lead to problems or not, depending whether the server accepts it.
[onCertificateRequest] :: ClientHooks -> ([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO (Maybe (CertificateChain, PrivKey))
[onNPNServerSuggest] :: ClientHooks -> Maybe ([ByteString] -> IO ByteString)
[onServerCertificate] :: ClientHooks -> CertificateStore -> ValidationCache -> ServiceID -> CertificateChain -> IO [FailedReason]
[onSuggestALPN] :: ClientHooks -> IO (Maybe [ByteString])

-- | A set of callbacks run by the server for various corners of the TLS
--   establishment
data ServerHooks
ServerHooks :: (CertificateChain -> IO CertificateUsage) -> IO Bool -> (Version -> [Cipher] -> Cipher) -> (Maybe HostName -> IO Credentials) -> IO (Maybe [ByteString]) -> (Measurement -> IO Bool) -> Maybe ([ByteString] -> IO ByteString) -> 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.
[onClientCertificate] :: ServerHooks -> CertificateChain -> IO CertificateUsage

-- | This action is called when the client certificate cannot be verified.
--   A <a>Nothing</a> argument indicates a wrong signature, a 'Just e'
--   message signals a crypto error.
[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.
[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.
[onServerNameIndication] :: ServerHooks -> Maybe HostName -> IO Credentials

-- | suggested next protocols accoring to the next protocol negotiation
--   extension.
[onSuggestNextProtocols] :: ServerHooks -> IO (Maybe [ByteString])

-- | at each new handshake, we call this hook to see if we allow handshake
--   to happens.
[onNewHandshake] :: ServerHooks -> Measurement -> IO Bool
[onALPNClientSuggest] :: ServerHooks -> Maybe ([ByteString] -> IO ByteString)

-- | List all the supported algorithms, versions, ciphers, etc supported.
data Supported
Supported :: [Version] -> [Cipher] -> [Compression] -> [HashAndSignatureAlgorithm] -> Bool -> Bool -> Bool -> Bool -> Bool -> 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 chosed.
[supportedVersions] :: Supported -> [Version]

-- | Supported cipher methods
[supportedCiphers] :: Supported -> [Cipher]

-- | supported compressions methods
[supportedCompressions] :: Supported -> [Compression]

-- | All supported hash/signature algorithms pair for client certificate
--   verification, ordered by decreasing priority.
[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.
[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.
[supportedClientInitiatedRenegotiation] :: Supported -> Bool

-- | Set if we support session.
[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.
[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.
[supportedEmptyPacket] :: Supported -> Bool
data Shared
Shared :: Credentials -> SessionManager -> CertificateStore -> ValidationCache -> Shared
[sharedCredentials] :: Shared -> Credentials
[sharedSessionManager] :: Shared -> SessionManager
[sharedCAStore] :: Shared -> CertificateStore
[sharedValidationCache] :: Shared -> ValidationCache

-- | A collection of hooks actions.
data Hooks
Hooks :: (Handshake -> IO Handshake) -> (CertificateChain -> IO ()) -> Logging -> Hooks

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

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

-- | hooks on IO and packets, receiving and sending.
[hookLogging] :: Hooks -> Logging

-- | Hooks for logging
--   
--   This is called when sending and receiving packets and IO
data Logging
Logging :: (String -> IO ()) -> (String -> IO ()) -> (ByteString -> IO ()) -> (Header -> ByteString -> IO ()) -> Logging
[loggingPacketSent] :: Logging -> String -> IO ()
[loggingPacketRecv] :: Logging -> String -> IO ()
[loggingIOSent] :: Logging -> ByteString -> IO ()
[loggingIORecv] :: Logging -> Header -> ByteString -> IO ()

-- | record some data about this connection.
data Measurement
Measurement :: !Word32 -> !Word32 -> !Word32 -> 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

-- | 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
CertificateRejectOther :: String -> CertificateRejectReason
defaultParamsClient :: HostName -> Bytes -> ClientParams
data MaxFragmentEnum
MaxFragment512 :: MaxFragmentEnum
MaxFragment1024 :: MaxFragmentEnum
MaxFragment2048 :: MaxFragmentEnum
MaxFragment4096 :: MaxFragmentEnum
type HashAndSignatureAlgorithm = (HashAlgorithm, SignatureAlgorithm)
data HashAlgorithm
HashNone :: HashAlgorithm
HashMD5 :: HashAlgorithm
HashSHA1 :: HashAlgorithm
HashSHA224 :: HashAlgorithm
HashSHA256 :: HashAlgorithm
HashSHA384 :: HashAlgorithm
HashSHA512 :: HashAlgorithm
HashOther :: Word8 -> HashAlgorithm
data SignatureAlgorithm
SignatureAnonymous :: SignatureAlgorithm
SignatureRSA :: SignatureAlgorithm
SignatureDSS :: SignatureAlgorithm
SignatureECDSA :: SignatureAlgorithm
SignatureOther :: Word8 -> SignatureAlgorithm
data CertificateType
CertificateType_RSA_Sign :: CertificateType
CertificateType_DSS_Sign :: CertificateType
CertificateType_RSA_Fixed_DH :: CertificateType
CertificateType_DSS_Fixed_DH :: CertificateType
CertificateType_RSA_Ephemeral_DH :: CertificateType
CertificateType_DSS_Ephemeral_DH :: CertificateType
CertificateType_fortezza_dms :: CertificateType
CertificateType_Unknown :: Word8 -> CertificateType
data ProtocolType
ProtocolType_ChangeCipherSpec :: ProtocolType
ProtocolType_Alert :: ProtocolType
ProtocolType_Handshake :: ProtocolType
ProtocolType_AppData :: ProtocolType
ProtocolType_DeprecatedHandshake :: ProtocolType
data Header
Header :: ProtocolType -> Version -> Word16 -> Header

-- | A session ID
type SessionID = ByteString

-- | Session data to resume
data SessionData
SessionData :: Version -> CipherID -> ByteString -> SessionData
[sessionVersion] :: SessionData -> Version
[sessionCipher] :: SessionData -> CipherID
[sessionSecret] :: SessionData -> ByteString

-- | A session manager
data SessionManager
SessionManager :: (SessionID -> IO (Maybe SessionData)) -> (SessionID -> SessionData -> IO ()) -> (SessionID -> IO ()) -> SessionManager

-- | used on server side to decide whether to resume a client session.
[sessionResume] :: SessionManager -> SessionID -> IO (Maybe SessionData)

-- | used when a session is established.
[sessionEstablish] :: SessionManager -> SessionID -> SessionData -> IO ()

-- | used when a session is invalidated.
[sessionInvalidate] :: SessionManager -> SessionID -> IO ()
noSessionManager :: SessionManager

-- | 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

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

-- | return the backend object associated with this context
ctxConnection :: Context -> Backend
class TLSParams a
class HasBackend a

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

-- | create a new context on an handle.

-- | <i>Deprecated: use contextNew</i>
contextNewOnHandle :: (MonadIO m, TLSParams params) => Handle -> params -> m Context

-- | create a new context on a socket.

-- | <i>Deprecated: use contextNew</i>
contextNewOnSocket :: (MonadIO m, TLSParams params) => Socket -> params -> m Context
contextFlush :: Context -> IO ()
contextClose :: Context -> IO ()
contextHookSetHandshakeRecv :: Context -> (Handshake -> IO Handshake) -> IO ()
contextHookSetCertificateRecv :: Context -> (CertificateChain -> IO ()) -> IO ()
contextHookSetLogging :: Context -> Logging -> IO ()
contextModifyHooks :: Context -> (Hooks -> Hooks) -> IO ()

-- | Information related to a running context, e.g. current cipher
data Information
Information :: Version -> Cipher -> Compression -> Maybe Bytes -> Maybe ClientRandom -> Maybe ServerRandom -> Information
[infoVersion] :: Information -> Version
[infoCipher] :: Information -> Cipher
[infoCompression] :: Information -> Compression
[infoMasterSecret] :: Information -> Maybe Bytes
[infoClientRandom] :: Information -> Maybe ClientRandom
[infoServerRandom] :: Information -> Maybe ServerRandom
unClientRandom :: ClientRandom -> Bytes
unServerRandom :: ServerRandom -> Bytes

-- | Information about the current context
contextGetInformation :: Context -> IO (Maybe Information)
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 :: Bytes -> Bytes -> 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 :: Bytes -> [Bytes] -> Bytes -> Either String Credential

-- | 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
bye :: MonadIO m => Context -> m ()

-- | Handshake for a new TLS connection This is to be called at the
--   beginning of a connection, and during renegotiation
handshake :: MonadIO m => Context -> m ()

-- | If the Next Protocol Negotiation extension has 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)

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

-- | recvData get data out of Data packet, and automatically renegotiate if
--   a Handshake ClientHello is received
recvData :: MonadIO m => Context -> m ByteString

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

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

-- | Public key types known and used in X.509
data PubKey :: *

-- | RSA public key
PubKeyRSA :: PublicKey -> PubKey

-- | DSA public key
PubKeyDSA :: PublicKey -> PubKey

-- | DH format with (p,g,q,j,(seed,pgenCounter))
PubKeyDH :: (Integer, Integer, Integer, Maybe Integer, ([Word8], Integer)) -> PubKey

-- | EC public key
PubKeyEC :: PubKeyEC -> PubKey

-- | unrecognized format
PubKeyUnknown :: OID -> ByteString -> PubKey

-- | Private key types known and used in X.509
data PrivKey :: *

-- | RSA private key
PrivKeyRSA :: PrivateKey -> PrivKey

-- | DSA private key
PrivKeyDSA :: PrivateKey -> PrivKey

-- | 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)

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

-- | Compression identification
type CompressionID = Word8

-- | default null compression
nullCompression :: Compression

-- | This is the default compression which is a NOOP.
data NullCompression

-- | return the associated ID for this algorithm
compressionID :: Compression -> CompressionID

-- | deflate (compress) a bytestring using a compression context and return
--   the result along with the new compression context.
compressionDeflate :: ByteString -> Compression -> (Compression, ByteString)

-- | inflate (decompress) a bytestring using a compression context and
--   return the result along the new compression context.
compressionInflate :: ByteString -> Compression -> (Compression, ByteString)

-- | intersect a list of ids commonly given by the other side with a list
--   of compression the function keeps the list of compression in order, to
--   be able to find quickly the prefered compression.
compressionIntersectID :: [Compression] -> [Word8] -> [Compression]
data CipherKeyExchangeType
CipherKeyExchange_RSA :: CipherKeyExchangeType
CipherKeyExchange_DH_Anon :: CipherKeyExchangeType
CipherKeyExchange_DHE_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDHE_RSA :: CipherKeyExchangeType
CipherKeyExchange_DHE_DSS :: CipherKeyExchangeType
CipherKeyExchange_DH_DSS :: CipherKeyExchangeType
CipherKeyExchange_DH_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDH_ECDSA :: CipherKeyExchangeType
CipherKeyExchange_ECDH_RSA :: CipherKeyExchangeType
CipherKeyExchange_ECDHE_ECDSA :: 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 algorithm
data Cipher
Cipher :: CipherID -> String -> Hash -> Bulk -> CipherKeyExchangeType -> Maybe Version -> Cipher
[cipherID] :: Cipher -> CipherID
[cipherName] :: Cipher -> String
[cipherHash] :: Cipher -> Hash
[cipherBulk] :: Cipher -> Bulk
[cipherKeyExchange] :: Cipher -> CipherKeyExchangeType
[cipherMinVer] :: Cipher -> Maybe Version

-- | 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
cipherExchangeNeedMoreData :: CipherKeyExchangeType -> Bool
hasMAC :: BulkFunctions -> Bool
hasRecordIV :: BulkFunctions -> Bool

-- | Versions known to TLS
--   
--   SSL2 is just defined, but this version is and will not be supported.
data Version
SSL2 :: Version
SSL3 :: Version
TLS10 :: Version
TLS11 :: Version
TLS12 :: Version

-- | TLSError that might be returned through the TLS stack
data TLSError

-- | mainly for instance of Error
Error_Misc :: String -> TLSError
Error_Protocol :: (String, Bool, 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
data KxError
RSAError :: Error -> KxError
KxUnsupported :: KxError
data AlertDescription
CloseNotify :: AlertDescription
UnexpectedMessage :: AlertDescription
BadRecordMac :: AlertDescription

-- | deprecated alert, should never be sent by compliant implementation
DecryptionFailed :: AlertDescription
RecordOverflow :: AlertDescription
DecompressionFailure :: AlertDescription
HandshakeFailure :: AlertDescription
BadCertificate :: AlertDescription
UnsupportedCertificate :: AlertDescription
CertificateRevoked :: AlertDescription
CertificateExpired :: AlertDescription
CertificateUnknown :: AlertDescription
IllegalParameter :: AlertDescription
UnknownCa :: AlertDescription
AccessDenied :: AlertDescription
DecodeError :: AlertDescription
DecryptError :: AlertDescription
ExportRestriction :: AlertDescription
ProtocolVersion :: AlertDescription
InsufficientSecurity :: AlertDescription
InternalError :: AlertDescription
InappropriateFallback :: AlertDescription
UserCanceled :: AlertDescription
NoRenegotiation :: AlertDescription
UnsupportedExtension :: AlertDescription
CertificateUnobtainable :: AlertDescription
UnrecognizedName :: AlertDescription
BadCertificateStatusResponse :: AlertDescription
BadCertificateHashValue :: AlertDescription

-- | TLS Exceptions related to bad user usage or asynchronous errors
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

-- | Usage error when the connection has not been established and the user
--   is trying to send or receive data
ConnectionNotEstablished :: TLSException

-- | A set of checks to activate or parametrize to perform on certificates.
--   
--   It's recommended to use <a>defaultChecks</a> to create the structure,
--   to better cope with future changes or expansion of the structure.
data ValidationChecks :: *
ValidationChecks :: Bool -> Maybe DateTime -> Bool -> Bool -> Bool -> Bool -> [ExtKeyUsageFlag] -> [ExtKeyUsagePurpose] -> Bool -> ValidationChecks

-- | check time validity of every certificate in the chain. the make sure
--   that current time is between each validity bounds in the certificate
[checkTimeValidity] :: ValidationChecks -> Bool

-- | The time when the validity check happens. When set to Nothing, the
--   current time will be used
[checkAtTime] :: ValidationChecks -> Maybe DateTime

-- | Check that no certificate is included that shouldn't be included.
--   unfortunately despite the specification violation, a lots of real
--   world server serves useless and usually old certificates that are not
--   relevant to the certificate sent, in their chain.
[checkStrictOrdering] :: ValidationChecks -> Bool

-- | Check that signing certificate got the CA basic constraint. this is
--   absolutely not recommended to turn it off.
[checkCAConstraints] :: ValidationChecks -> Bool

-- | Check the whole certificate chain without stopping at the first
--   failure. Allow gathering a exhaustive list of failure reasons. if this
--   is turn off, it's absolutely not safe to ignore a failed reason even
--   it doesn't look serious (e.g. Expired) as other more serious checks
--   would not have been performed.
[checkExhaustive] :: ValidationChecks -> Bool

-- | Check that the leaf certificate is version 3. If disable, version 2
--   certificate is authorized in leaf position and key usage cannot be
--   checked.
[checkLeafV3] :: ValidationChecks -> Bool

-- | Check that the leaf certificate is authorized to be used for certain
--   usage. If set to empty list no check are performed, otherwise all the
--   flags is the list need to exists in the key usage extension. If the
--   extension is not present, the check will pass and behave as if the
--   certificate key is not restricted to any specific usage.
[checkLeafKeyUsage] :: ValidationChecks -> [ExtKeyUsageFlag]

-- | Check that the leaf certificate is authorized to be used for certain
--   purpose. If set to empty list no check are performed, otherwise all
--   the flags is the list need to exists in the extended key usage
--   extension if present. If the extension is not present, then the check
--   will pass and behave as if the certificate is not restricted to any
--   specific purpose.
[checkLeafKeyPurpose] :: ValidationChecks -> [ExtKeyUsagePurpose]

-- | Check the top certificate names matching the fully qualified hostname
--   (FQHN). it's not recommended to turn this check off, if no other name
--   checks are performed.
[checkFQHN] :: ValidationChecks -> Bool

-- | A set of hooks to manipulate the way the verification works.
--   
--   BEWARE, it's easy to change behavior leading to compromised security.
data ValidationHooks :: *
ValidationHooks :: (DistinguishedName -> Certificate -> Bool) -> (DateTime -> Certificate -> [FailedReason]) -> (HostName -> Certificate -> [FailedReason]) -> ([FailedReason] -> [FailedReason]) -> ValidationHooks

-- | check the the issuer <a>DistinguishedName</a> match the subject
--   <a>DistinguishedName</a> of a certificate.
[hookMatchSubjectIssuer] :: ValidationHooks -> DistinguishedName -> Certificate -> Bool

-- | validate that the parametrized time valide with the certificate in
--   argument
[hookValidateTime] :: ValidationHooks -> DateTime -> Certificate -> [FailedReason]

-- | validate the certificate leaf name with the DNS named used to connect
[hookValidateName] :: ValidationHooks -> HostName -> Certificate -> [FailedReason]

-- | user filter to modify the list of failure reasons
[hookFilterReason] :: ValidationHooks -> [FailedReason] -> [FailedReason]

-- | All the callbacks needed for querying and adding to the cache.
data ValidationCache :: *
ValidationCache :: ValidationCacheQueryCallback -> ValidationCacheAddCallback -> ValidationCache

-- | cache querying callback
[cacheQuery] :: ValidationCache -> ValidationCacheQueryCallback

-- | cache adding callback
[cacheAdd] :: ValidationCache -> ValidationCacheAddCallback

-- | The result of a cache query
data ValidationCacheResult :: *

-- | cache allow this fingerprint to go through
ValidationCachePass :: ValidationCacheResult

-- | cache denied this fingerprint for further validation
ValidationCacheDenied :: String -> ValidationCacheResult

-- | unknown fingerprint in cache
ValidationCacheUnknown :: ValidationCacheResult

-- | create a simple constant cache that list exceptions to the
--   certification validation. Typically this is use to allow self-signed
--   certificates for specific use, with out-of-bounds user checks.
--   
--   No fingerprints will be added after the instance is created.
--   
--   The underlying structure for the check is kept as a list, as usually
--   the exception list will be short, but when the list go above a dozen
--   exceptions it's recommended to use another cache mechanism with a
--   faster lookup mechanism (hashtable, map, etc).
--   
--   Note that only one fingerprint is allowed per ServiceID, for other
--   use, another cache mechanism need to be use.
exceptionValidationCache :: [(ServiceID, Fingerprint)] -> ValidationCache


module Network.TLS.Extra.Cipher

-- | all encrypted ciphers supported ordered from strong to weak. this
--   choice of ciphersuite should satisfy most normal need
ciphersuite_all :: [Cipher]

-- | list of medium ciphers.
ciphersuite_medium :: [Cipher]

-- | the strongest ciphers supported.
ciphersuite_strong :: [Cipher]

-- | all unencrypted ciphers, do not use on insecure network.
ciphersuite_unencrypted :: [Cipher]

-- | DHE-RSA cipher suite
ciphersuite_dhe_rsa :: [Cipher]
ciphersuite_dhe_dss :: [Cipher]

-- | unencrypted cipher using RSA for key exchange and SHA1 for digest
cipher_null_SHA1 :: Cipher

-- | unencrypted cipher using RSA for key exchange and MD5 for digest
cipher_null_MD5 :: Cipher

-- | RC4 cipher, RSA key exchange and MD5 for digest
cipher_RC4_128_MD5 :: Cipher

-- | RC4 cipher, RSA key exchange and SHA1 for digest
cipher_RC4_128_SHA1 :: Cipher

-- | AES cipher (128 bit key), RSA key exchange and SHA1 for digest
cipher_AES128_SHA1 :: Cipher

-- | AES cipher (256 bit key), RSA key exchange and SHA1 for digest
cipher_AES256_SHA1 :: Cipher

-- | AES cipher (128 bit key), RSA key exchange and SHA256 for digest
cipher_AES128_SHA256 :: Cipher

-- | AES cipher (256 bit key), RSA key exchange and SHA256 for digest
cipher_AES256_SHA256 :: Cipher

-- | 3DES cipher (168 bit key), RSA key exchange and SHA1 for digest
cipher_RSA_3DES_EDE_CBC_SHA1 :: Cipher

-- | AES cipher (128 bit key), DHE key exchanged signed by RSA and SHA1 for
--   digest
cipher_DHE_RSA_AES128_SHA1 :: Cipher

-- | AES cipher (256 bit key), DHE key exchanged signed by RSA and SHA1 for
--   digest
cipher_DHE_RSA_AES256_SHA1 :: Cipher
cipher_DHE_RSA_AES128_SHA256 :: Cipher
cipher_DHE_RSA_AES256_SHA256 :: Cipher

-- | AES cipher (128 bit key), DHE key exchanged signed by DSA and SHA1 for
--   digest
cipher_DHE_DSS_AES128_SHA1 :: Cipher

-- | AES cipher (256 bit key), DHE key exchanged signed by DSA and SHA1 for
--   digest
cipher_DHE_DSS_AES256_SHA1 :: Cipher
cipher_DHE_DSS_RC4_SHA1 :: Cipher
cipher_DHE_RSA_AES128GCM_SHA256 :: Cipher
cipher_ECDHE_RSA_AES128GCM_SHA256 :: Cipher
cipher_ECDHE_RSA_AES256GCM_SHA384 :: Cipher
cipher_ECDHE_RSA_AES128CBC_SHA256 :: Cipher
cipher_ECDHE_RSA_AES128CBC_SHA :: Cipher
cipher_ECDHE_RSA_AES256CBC_SHA :: Cipher
cipher_ECDHE_RSA_AES256CBC_SHA384 :: Cipher
cipher_ECDHE_ECDSA_AES128GCM_SHA256 :: Cipher


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