-- 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,
--   with only RSA supported for Key Exchange.
--   
--   Only core protocol available here, have a look at the
--   <a>http://hackage.haskell.org/package/tls-extra/</a> package for
--   default ciphers, compressions and certificates functions.
@package tls
@version 1.0.2


module Network.TLS
data Params
Params :: Version -> [Version] -> [Cipher] -> [Compression] -> [HashAndSignatureAlgorithm] -> Bool -> Bool -> [(X509, Maybe PrivateKey)] -> Logging -> (Measurement -> IO Bool) -> ([X509] -> IO CertificateUsage) -> s -> IO (Maybe [ByteString]) -> Maybe ([ByteString] -> IO ByteString) -> RoleParams -> Params

-- | version to use on client connection.
pConnectVersion :: Params -> Version

-- | allowed versions that we can use.
pAllowedVersions :: Params -> [Version]

-- | all ciphers supported ordered by priority.
pCiphers :: Params -> [Cipher]

-- | all compression supported ordered by priority.
pCompressions :: Params -> [Compression]

-- | All supported hash/signature algorithms pair for client certificate
--   verification, ordered by decreasing priority.
pHashSignatures :: Params -> [HashAndSignatureAlgorithm]

-- | notify that we want to use secure renegotation
pUseSecureRenegotiation :: Params -> Bool

-- | generate new session if specified
pUseSession :: Params -> Bool

-- | the cert chain for this context with the associated keys if any.
pCertificates :: Params -> [(X509, Maybe PrivateKey)]

-- | callback for logging
pLogging :: Params -> Logging

-- | callback on a beggining of handshake
onHandshake :: Params -> Measurement -> IO Bool

-- | callback to verify received cert chain.
onCertificatesRecv :: Params -> [X509] -> IO CertificateUsage
pSessionManager :: Params -> s

-- | suggested next protocols accoring to the next protocol negotiation
--   extension.
onSuggestNextProtocols :: Params -> IO (Maybe [ByteString])
onNPNServerSuggest :: Params -> Maybe ([ByteString] -> IO ByteString)
roleParams :: Params -> RoleParams
data RoleParams
Client :: ClientParams -> RoleParams
Server :: ServerParams -> RoleParams
data ClientParams
ClientParams :: Maybe MaxFragmentEnum -> Maybe HostName -> Maybe (SessionID, SessionData) -> (([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO [(X509, Maybe PrivateKey)]) -> ClientParams
clientUseMaxFragmentLength :: ClientParams -> Maybe MaxFragmentEnum
clientUseServerName :: ClientParams -> Maybe HostName

-- | try to establish a connection using this session.
clientWantSessionResume :: ClientParams -> Maybe (SessionID, SessionData)

-- | 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 :: ClientParams -> ([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO [(X509, Maybe PrivateKey)]
data ServerParams
ServerParams :: Bool -> [X509] -> ([X509] -> IO CertificateUsage) -> (Maybe KxError -> IO Bool) -> (Version -> [Cipher] -> Cipher) -> 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 -> [X509]

-- | 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 :: ServerParams -> [X509] -> 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 :: ServerParams -> Maybe KxError -> IO Bool

-- | callback on server to modify the cipher chosen.
onCipherChoosing :: ServerParams -> Version -> [Cipher] -> Cipher
updateClientParams :: (ClientParams -> ClientParams) -> Params -> Params
updateServerParams :: (ServerParams -> ServerParams) -> Params -> Params
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 :: Params
defaultParamsServer :: Params
defaultLogging :: Logging
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
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
class SessionManager a
sessionResume :: SessionManager a => a -> SessionID -> IO (Maybe SessionData)
sessionEstablish :: SessionManager a => a -> SessionID -> SessionData -> IO ()
sessionInvalidate :: SessionManager a => a -> SessionID -> IO ()
data NoSessionManager
NoSessionManager :: NoSessionManager

-- | Set a new session manager in a parameters structure.
setSessionManager :: SessionManager s => s -> Params -> Params

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

-- | create a new context using the backend and parameters specified.
contextNew :: (MonadIO m, CryptoRandomGen rng) => Backend -> Params -> rng -> m Context

-- | create a new context on an handle.
contextNewOnHandle :: (MonadIO m, CryptoRandomGen rng) => Handle -> Params -> rng -> m Context
contextFlush :: Context -> IO ()
contextClose :: Context -> IO ()
type TLSParams = Params
type TLSLogging = Logging
type TLSCertificateUsage = CertificateUsage
type TLSCertificateRejectReason = CertificateRejectReason
type TLSCtx = Context
defaultParams :: Params

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

-- | 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.
recvData' :: MonadIO m => Context -> m ByteString
data PrivateKey
PrivRSA :: PrivateKey -> PrivateKey

-- | 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 BulkFunctions
BulkNoneF :: BulkFunctions
BulkBlockF :: (Key -> IV -> ByteString -> ByteString) -> (Key -> IV -> ByteString -> ByteString) -> BulkFunctions
BulkStreamF :: (Key -> IV) -> (IV -> ByteString -> (ByteString, IV)) -> (IV -> ByteString -> (ByteString, IV)) -> BulkFunctions
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 -> BulkFunctions -> Bulk
bulkName :: Bulk -> String
bulkKeySize :: Bulk -> Int
bulkIVSize :: Bulk -> Int
bulkBlockSize :: Bulk -> Int
bulkF :: Bulk -> BulkFunctions
data Hash
Hash :: String -> Int -> (ByteString -> ByteString) -> Hash
hashName :: Hash -> String
hashSize :: Hash -> Int
hashF :: Hash -> ByteString -> ByteString

-- | 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 Key = ByteString
type IV = ByteString
cipherExchangeNeedMoreData :: CipherKeyExchangeType -> 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_Random :: String -> TLSError
Error_EOF :: TLSError
Error_Packet :: String -> TLSError
Error_Packet_Size_Mismatch :: (Int, Int) -> TLSError
Error_Packet_unexpected :: String -> String -> TLSError
Error_Packet_Parsing :: String -> TLSError
Error_Internal_Packet_ByteProcessed :: Int -> Int -> Int -> TLSError
Error_Unknown_Version :: Word8 -> Word8 -> TLSError
Error_Unknown_Type :: String -> TLSError
data KxError
RSAError :: Error -> 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
UserCanceled :: AlertDescription
NoRenegotiation :: AlertDescription
UnsupportedExtension :: AlertDescription
CertificateUnobtainable :: AlertDescription
UnrecognizedName :: AlertDescription
BadCertificateStatusResponse :: AlertDescription
BadCertificateHashValue :: AlertDescription
data HandshakeFailed
HandshakeFailed :: TLSError -> HandshakeFailed
data ConnectionNotEstablished
ConnectionNotEstablished :: ConnectionNotEstablished