tls-1.1.5: TLS/SSL protocol native implementation (Server and Client)

Portability | unknown
Stability | experimental
Maintainer | Vincent Hanquez <vincent@snarc.org>
Safe Haskell | None

Network.TLS

Contents

- Context configuration
- raw types
- Session
- Backend abstraction
- Context object
- Creating a context
- deprecated type aliases
- deprecated values
- Initialisation and Termination of context
- Next Protocol Negotiation
- High level API
- Crypto Key
- Compressions & Predefined compressions
- member redefined for the class abstraction
- helper
- Ciphers & Predefined ciphers
- Versions
- Errors
- Exceptions

Description

Synopsis

- data Params = forall s . SessionManager s => Params {
  - pConnectVersion :: Version
  - pAllowedVersions :: [Version]
  - pCiphers :: [Cipher]
  - pCompressions :: [Compression]
  - pHashSignatures :: [HashAndSignatureAlgorithm]
  - pUseSecureRenegotiation :: Bool
  - pUseSession :: Bool
  - pCertificates :: [(X509, Maybe PrivateKey)]
  - pLogging :: Logging
  - onHandshake :: Measurement -> IO Bool
  - onCertificatesRecv :: [X509] -> IO CertificateUsage
  - pSessionManager :: s
  - onSuggestNextProtocols :: IO (Maybe [ByteString])
  - onNPNServerSuggest :: Maybe ([ByteString] -> IO ByteString)
  - roleParams :: RoleParams
  }
- data RoleParams
  - = Client ClientParams
  - | Server ServerParams
- data ClientParams = ClientParams {
  - clientUseMaxFragmentLength :: Maybe MaxFragmentEnum
  - clientUseServerName :: Maybe HostName
  - clientWantSessionResume :: Maybe (SessionID, SessionData)
  - onCertificateRequest :: ([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO [(X509, Maybe PrivateKey)]
  }
- data ServerParams = ServerParams {
  - serverWantClientCert :: Bool
  - serverCACertificates :: [X509]
  - onClientCertificate :: [X509] -> IO CertificateUsage
  - onUnverifiedClientCert :: IO Bool
  - onCipherChoosing :: Version -> [Cipher] -> Cipher
  }
- updateClientParams :: (ClientParams -> ClientParams) -> Params -> Params
- updateServerParams :: (ServerParams -> ServerParams) -> Params -> Params
- data Logging = Logging {
  - loggingPacketSent :: String -> IO ()
  - loggingPacketRecv :: String -> IO ()
  - loggingIOSent :: ByteString -> IO ()
  - loggingIORecv :: Header -> ByteString -> IO ()
  }
- data Measurement = Measurement {
  - nbHandshakes :: !Word32
  - bytesReceived :: !Word32
  - bytesSent :: !Word32
  }
- data CertificateUsage
  - = CertificateUsageAccept
  - | CertificateUsageReject CertificateRejectReason
- data CertificateRejectReason
  - = CertificateRejectExpired
  - | CertificateRejectRevoked
  - | CertificateRejectUnknownCA
  - | CertificateRejectOther String
- defaultParamsClient :: Params
- defaultParamsServer :: Params
- defaultLogging :: Logging
- data MaxFragmentEnum
  - = MaxFragment512
  - | MaxFragment1024
  - | MaxFragment2048
  - | MaxFragment4096
- type HashAndSignatureAlgorithm = (HashAlgorithm, SignatureAlgorithm)
- data HashAlgorithm
  - = HashNone
  - | HashMD5
  - | HashSHA1
  - | HashSHA224
  - | HashSHA256
  - | HashSHA384
  - | HashSHA512
  - | HashOther Word8
- data SignatureAlgorithm
  - = SignatureAnonymous
  - | SignatureRSA
  - | SignatureDSS
  - | SignatureECDSA
  - | SignatureOther Word8
- data CertificateType
  - = CertificateType_RSA_Sign
  - | CertificateType_DSS_Sign
  - | CertificateType_RSA_Fixed_DH
  - | CertificateType_DSS_Fixed_DH
  - | CertificateType_RSA_Ephemeral_DH
  - | CertificateType_DSS_Ephemeral_DH
  - | CertificateType_fortezza_dms
  - | CertificateType_Unknown Word8
- data ProtocolType
  - = ProtocolType_ChangeCipherSpec
  - | ProtocolType_Alert
  - | ProtocolType_Handshake
  - | ProtocolType_AppData
  - | ProtocolType_DeprecatedHandshake
- data Header = Header ProtocolType Version Word16
- type SessionID = ByteString
- data SessionData = SessionData {
  - sessionVersion :: Version
  - sessionCipher :: CipherID
  - sessionSecret :: ByteString
  }
- class SessionManager a where
  - sessionResume :: a -> SessionID -> IO (Maybe SessionData)
  - sessionEstablish :: a -> SessionID -> SessionData -> IO ()
  - sessionInvalidate :: a -> SessionID -> IO ()
- data NoSessionManager = NoSessionManager
- setSessionManager :: SessionManager s => s -> Params -> Params
- data Backend = Backend {
  - backendFlush :: IO ()
  - backendClose :: IO ()
  - backendSend :: ByteString -> IO ()
  - backendRecv :: Int -> IO ByteString
  }
- data Context
- ctxConnection :: Context -> Backend
- contextNew :: (MonadIO m, CPRG rng) => Backend -> Params -> rng -> m Context
- contextNewOnHandle :: (MonadIO m, CPRG 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
- bye :: MonadIO m => Context -> m ()
- handshake :: MonadIO m => Context -> m ()
- getNegotiatedProtocol :: MonadIO m => Context -> m (Maybe ByteString)
- sendData :: MonadIO m => Context -> ByteString -> m ()
- recvData :: MonadIO m => Context -> m ByteString
- recvData' :: MonadIO m => Context -> m ByteString
- data PrivateKey = PrivRSA PrivateKey
- class CompressionC a where
  - compressionCID :: a -> CompressionID
  - compressionCDeflate :: a -> ByteString -> (a, ByteString)
  - compressionCInflate :: a -> ByteString -> (a, ByteString)
- data Compression = forall a . CompressionC a => Compression a
- type CompressionID = Word8
- nullCompression :: Compression
- data NullCompression
- compressionID :: Compression -> CompressionID
- compressionDeflate :: ByteString -> Compression -> (Compression, ByteString)
- compressionInflate :: ByteString -> Compression -> (Compression, ByteString)
- compressionIntersectID :: [Compression] -> [Word8] -> [Compression]
- data BulkFunctions
  - = BulkBlockF (Key -> IV -> ByteString -> ByteString) (Key -> IV -> ByteString -> ByteString)
  - | BulkStreamF (Key -> IV) (IV -> ByteString -> (ByteString, IV)) (IV -> ByteString -> (ByteString, IV))
- data CipherKeyExchangeType
  - = CipherKeyExchange_RSA
  - | CipherKeyExchange_DH_Anon
  - | CipherKeyExchange_DHE_RSA
  - | CipherKeyExchange_ECDHE_RSA
  - | CipherKeyExchange_DHE_DSS
  - | CipherKeyExchange_DH_DSS
  - | CipherKeyExchange_DH_RSA
  - | CipherKeyExchange_ECDH_ECDSA
  - | CipherKeyExchange_ECDH_RSA
  - | CipherKeyExchange_ECDHE_ECDSA
- data Bulk = Bulk {
  - bulkName :: String
  - bulkKeySize :: Int
  - bulkIVSize :: Int
  - bulkBlockSize :: Int
  - bulkF :: BulkFunctions
  }
- data Hash = Hash {
  - hashName :: String
  - hashSize :: Int
  - hashF :: ByteString -> ByteString
  }
- data Cipher = Cipher {
  - cipherID :: CipherID
  - cipherName :: String
  - cipherHash :: Hash
  - cipherBulk :: Bulk
  - cipherKeyExchange :: CipherKeyExchangeType
  - cipherMinVer :: Maybe Version
  }
- type CipherID = Word16
- cipherKeyBlockSize :: Cipher -> Int
- type Key = ByteString
- type IV = ByteString
- cipherExchangeNeedMoreData :: CipherKeyExchangeType -> Bool
- data Version
  - = SSL2
  - | SSL3
  - | TLS10
  - | TLS11
  - | TLS12
- data TLSError
  - = Error_Misc String
  - | Error_Protocol (String, Bool, AlertDescription)
  - | Error_Certificate String
  - | Error_HandshakePolicy String
  - | Error_EOF
  - | Error_Packet String
  - | Error_Packet_unexpected String String
  - | Error_Packet_Parsing String
- data KxError = RSAError Error
- data AlertDescription
  - = CloseNotify
  - | UnexpectedMessage
  - | BadRecordMac
  - | DecryptionFailed
  - | RecordOverflow
  - | DecompressionFailure
  - | HandshakeFailure
  - | BadCertificate
  - | UnsupportedCertificate
  - | CertificateRevoked
  - | CertificateExpired
  - | CertificateUnknown
  - | IllegalParameter
  - | UnknownCa
  - | AccessDenied
  - | DecodeError
  - | DecryptError
  - | ExportRestriction
  - | ProtocolVersion
  - | InsufficientSecurity
  - | InternalError
  - | UserCanceled
  - | NoRenegotiation
  - | UnsupportedExtension
  - | CertificateUnobtainable
  - | UnrecognizedName
  - | BadCertificateStatusResponse
  - | BadCertificateHashValue
- data Terminated = Terminated Bool String TLSError
- data HandshakeFailed = HandshakeFailed TLSError
- data ConnectionNotEstablished = ConnectionNotEstablished

# Context configuration

data Params Source

Constructors

forall s . SessionManager s => Params |

Fields

pConnectVersion :: Version

  version to use on client connection.

pAllowedVersions :: [Version]

  allowed versions that we can use.

pCiphers :: [Cipher]

  all ciphers supported ordered by priority.

pCompressions :: [Compression]

  all compression supported ordered by priority.

pHashSignatures :: [HashAndSignatureAlgorithm]

  All supported hash/signature algorithms pair for client certificate verification, ordered by decreasing priority.

pUseSecureRenegotiation :: Bool

  notify that we want to use secure renegotation

pUseSession :: Bool

  generate new session if specified

pCertificates :: [(X509, Maybe PrivateKey)]

  the cert chain for this context with the associated keys if any.

pLogging :: Logging

  callback for logging

onHandshake :: Measurement -> IO Bool

  callback on a beggining of handshake

onCertificatesRecv :: [X509] -> IO CertificateUsage

  callback to verify received cert chain.

pSessionManager :: s
onSuggestNextProtocols :: IO (Maybe [ByteString])

  suggested next protocols accoring to the next protocol negotiation extension.

onNPNServerSuggest :: Maybe ([ByteString] -> IO ByteString)
roleParams :: RoleParams

Instances

Show Params |

data RoleParams Source

Constructors

Client ClientParams |
Server ServerParams |

data ClientParams Source

Constructors

ClientParams |

Fields

clientUseMaxFragmentLength :: Maybe MaxFragmentEnum
clientUseServerName :: Maybe HostName
clientWantSessionResume :: Maybe (SessionID, SessionData)

  try to establish a connection using this session.

onCertificateRequest :: ([CertificateType], Maybe [HashAndSignatureAlgorithm], [DistinguishedName]) -> IO [(X509, Maybe PrivateKey)]

  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.

data ServerParams Source

Constructors

ServerParams |

Fields

serverWantClientCert :: Bool

  request a certificate from client.

serverCACertificates :: [X509]

  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.

onClientCertificate :: [X509] -> IO CertificateUsage

  This action is called when a client certificate chain is received from the client. When it returns a CertificateUsageReject value, the handshake is aborted.

onUnverifiedClientCert :: IO Bool

  This action is called when the client certificate cannot be verified. A `Nothing` argument indicates a wrong signature, a 'Just e' message signals a crypto error.

onCipherChoosing :: Version -> [Cipher] -> Cipher

  callback on server to modify the cipher chosen.

updateClientParams :: (ClientParams -> ClientParams) -> Params -> Params Source

updateServerParams :: (ServerParams -> ServerParams) -> Params -> Params Source

data Logging Source

Constructors

Logging |

Fields

loggingPacketSent :: String -> IO ()
loggingPacketRecv :: String -> IO ()
loggingIOSent :: ByteString -> IO ()
loggingIORecv :: Header -> ByteString -> IO ()

data Measurement Source

record some data about this connection.

Constructors

Measurement |

Fields

nbHandshakes :: !Word32

  number of handshakes on this context

bytesReceived :: !Word32

  bytes received since last handshake

bytesSent :: !Word32

  bytes sent since last handshake

Instances

Eq Measurement |
Show Measurement |

data CertificateUsage Source

Certificate Usage callback possible returns values.

Constructors

CertificateUsageAccept | usage of certificate accepted
CertificateUsageReject CertificateRejectReason | usage of certificate rejected

Instances

Eq CertificateUsage |
Show CertificateUsage |

data CertificateRejectReason Source

Certificate and Chain rejection reason

Constructors

CertificateRejectExpired |
CertificateRejectRevoked |
CertificateRejectUnknownCA |
CertificateRejectOther String |

Instances

Eq CertificateRejectReason |
Show CertificateRejectReason |

defaultParamsClient :: Params Source

defaultParamsServer :: Params Source

defaultLogging :: Logging Source

data MaxFragmentEnum Source

Constructors

MaxFragment512 |
MaxFragment1024 |
MaxFragment2048 |
MaxFragment4096 |

Instances

Eq MaxFragmentEnum |
Show MaxFragmentEnum |

type HashAndSignatureAlgorithm = (HashAlgorithm, SignatureAlgorithm)Source

data HashAlgorithm Source

Constructors

HashNone |
HashMD5 |
HashSHA1 |
HashSHA224 |
HashSHA256 |
HashSHA384 |
HashSHA512 |
HashOther Word8 |

Instances

Eq HashAlgorithm |
Show HashAlgorithm |

data SignatureAlgorithm Source

Constructors

SignatureAnonymous |
SignatureRSA |
SignatureDSS |
SignatureECDSA |
SignatureOther Word8 |

Instances

Eq SignatureAlgorithm |
Show SignatureAlgorithm |

data CertificateType Source

Constructors

CertificateType_RSA_Sign |
CertificateType_DSS_Sign |
CertificateType_RSA_Fixed_DH |
CertificateType_DSS_Fixed_DH |
CertificateType_RSA_Ephemeral_DH |
CertificateType_DSS_Ephemeral_DH |
CertificateType_fortezza_dms |
CertificateType_Unknown Word8 |

Instances

Eq CertificateType |
Show CertificateType |

# raw types

data ProtocolType Source

Constructors

ProtocolType_ChangeCipherSpec |
ProtocolType_Alert |
ProtocolType_Handshake |
ProtocolType_AppData |
ProtocolType_DeprecatedHandshake |

Instances

Eq ProtocolType |
Show ProtocolType |

data Header Source

Constructors

Header ProtocolType Version Word16 |

Instances

Eq Header |
Show Header |

# Session

type SessionID = ByteString Source

A session ID

data SessionData Source

Session data to resume

Constructors

SessionData |

Fields

sessionVersion :: Version
sessionCipher :: CipherID
sessionSecret :: ByteString

class SessionManager a where Source

A session manager

Methods

sessionResume :: a -> SessionID -> IO (Maybe SessionData)Source

used on server side to decide whether to resume a client session

sessionEstablish :: a -> SessionID -> SessionData -> IO ()Source

used when a session is established.

sessionInvalidate :: a -> SessionID -> IO ()Source

used when a session is invalidated

Instances

SessionManager NoSessionManager |

data NoSessionManager Source

Constructors

NoSessionManager |

Instances

SessionManager NoSessionManager |

setSessionManager :: SessionManager s => s -> Params -> Params Source

Set a new session manager in a parameters structure.

# Backend abstraction

data Backend Source

Connection IO backend

Constructors

Backend |

Fields

backendFlush :: IO ()

  Flush the connection sending buffer, if any.

backendClose :: IO ()

  Close the connection.

backendSend :: ByteString -> IO ()

  Send a bytestring through the connection.

backendRecv :: Int -> IO ByteString

  Receive specified number of bytes from the connection.

# Context object

data Context Source

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

ctxConnection :: Context -> Backend Source

return the backend object associated with this context

# Creating a context

contextNew Source

Arguments

:: (MonadIO m, CPRG rng) |
=> Backend | Backend abstraction with specific method to interact with the connection type.
-> Params | Parameters of the context.
-> rng | Random number generator associated with this context.
-> m Context |

create a new context using the backend and parameters specified.

contextNewOnHandle Source

Arguments

:: (MonadIO m, CPRG rng) |
=> Handle | Handle of the connection.
-> Params | Parameters of the context.
-> rng | Random number generator associated with this context.
-> m Context |

create a new context on an handle.

contextFlush :: Context -> IO ()Source

contextClose :: Context -> IO ()Source

# deprecated type aliases

type TLSParams = Params Source

type TLSLogging = Logging Source

type TLSCertificateUsage = CertificateUsage Source

type TLSCertificateRejectReason = CertificateRejectReason Source

type TLSCtx = Context Source

# deprecated values

defaultParams :: Params Source

Deprecated: use defaultParamsClient

# Initialisation and Termination of context

bye :: MonadIO m => Context -> m ()Source

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 < TLS1.2).

this doesn't actually close the handle

handshake :: MonadIO m => Context -> m ()Source

Handshake for a new TLS connection This is to be called at the beginning of a connection, and during renegotiation

# Next Protocol Negotiation

getNegotiatedProtocol :: MonadIO m => Context -> m (Maybe ByteString)Source

If the Next Protocol Negotiation extension has been used, this will return get the protocol agreed upon.

# High level API

sendData :: MonadIO m => Context -> ByteString -> m ()Source

sendData sends a bunch of data. It will automatically chunk data to acceptable packet size

recvData :: MonadIO m => Context -> m ByteString Source

recvData get data out of Data packet, and automatically renegotiate if a Handshake ClientHello is received

recvData' :: MonadIO m => Context -> m ByteString Source

Deprecated: use recvData that returns strict bytestring

same as recvData but returns a lazy bytestring.

# Crypto Key

data PrivateKey Source

Constructors

PrivRSA PrivateKey |

Instances

Show PrivateKey |

# Compressions & Predefined compressions

class CompressionC a where Source

supported compression algorithms need to be part of this class

Methods

compressionCID :: a -> CompressionID Source

compressionCDeflate :: a -> ByteString -> (a, ByteString)Source

compressionCInflate :: a -> ByteString -> (a, ByteString)Source

data Compression Source

every compression need to be wrapped in this, to fit in structure

Constructors

forall a . CompressionC a => Compression a |

Instances

Show Compression |

type CompressionID = Word8 Source

Compression identification

nullCompression :: Compression Source

default null compression

data NullCompression Source

This is the default compression which is a NOOP.

# member redefined for the class abstraction

compressionID :: Compression -> CompressionID Source

return the associated ID for this algorithm

compressionDeflate :: ByteString -> Compression -> (Compression, ByteString)Source

deflate (compress) a bytestring using a compression context and return the result along with the new compression context.

compressionInflate :: ByteString -> Compression -> (Compression, ByteString)Source

inflate (decompress) a bytestring using a compression context and return the result along the new compression context.

# helper

compressionIntersectID :: [Compression] -> [Word8] -> [Compression]Source

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.

# Ciphers & Predefined ciphers

data BulkFunctions Source

Constructors

BulkBlockF (Key -> IV -> ByteString -> ByteString) (Key -> IV -> ByteString -> ByteString) |
BulkStreamF (Key -> IV) (IV -> ByteString -> (ByteString, IV)) (IV -> ByteString -> (ByteString, IV)) |

data CipherKeyExchangeType Source

Constructors

CipherKeyExchange_RSA |
CipherKeyExchange_DH_Anon |
CipherKeyExchange_DHE_RSA |
CipherKeyExchange_ECDHE_RSA |
CipherKeyExchange_DHE_DSS |
CipherKeyExchange_DH_DSS |
CipherKeyExchange_DH_RSA |
CipherKeyExchange_ECDH_ECDSA |
CipherKeyExchange_ECDH_RSA |
CipherKeyExchange_ECDHE_ECDSA |

Instances

Eq CipherKeyExchangeType |
Show CipherKeyExchangeType |

data Bulk Source

Constructors

Bulk |

Fields

bulkName :: String
bulkKeySize :: Int
bulkIVSize :: Int
bulkBlockSize :: Int
bulkF :: BulkFunctions

data Hash Source

Constructors

Hash |

Fields

hashName :: String
hashSize :: Int
hashF :: ByteString -> ByteString

data Cipher Source

Cipher algorithm

Constructors

Cipher |

Fields

cipherID :: CipherID
cipherName :: String
cipherHash :: Hash
cipherBulk :: Bulk
cipherKeyExchange :: CipherKeyExchangeType
cipherMinVer :: Maybe Version

Instances

Eq Cipher |
Show Cipher |

type CipherID = Word16 Source

Cipher identification

cipherKeyBlockSize :: Cipher -> Int Source

type Key = ByteString Source

type IV = ByteString Source

cipherExchangeNeedMoreData :: CipherKeyExchangeType -> Bool Source

# Versions

data Version Source

Versions known to TLS

SSL2 is just defined, but this version is and will not be supported.

Constructors

SSL2 |
SSL3 |
TLS10 |
TLS11 |
TLS12 |

Instances

Eq Version |
Ord Version |
Show Version |

# Errors

data TLSError Source

TLSError that might be returned through the TLS stack

Constructors

Error_Misc String | mainly for instance of Error
Error_Protocol (String, Bool, AlertDescription) |
Error_Certificate String |
Error_HandshakePolicy String | handshake policy failed.
Error_EOF |
Error_Packet String |
Error_Packet_unexpected String String |
Error_Packet_Parsing String |

Instances

Eq TLSError |
Show TLSError |
Typeable TLSError |
Exception TLSError |
Error TLSError |

data KxError Source

Constructors

RSAError Error |

Instances

Show KxError |

data AlertDescription Source

Constructors

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

Instances

Eq AlertDescription |
Show AlertDescription |

# Exceptions

data Terminated Source

Early termination exception with the reason and the TLS error associated

Constructors

Terminated Bool String TLSError |

Instances

Eq Terminated |
Show Terminated |
Typeable Terminated |
Exception Terminated |

data HandshakeFailed Source

Constructors

HandshakeFailed TLSError |

Instances

Eq HandshakeFailed |
Show HandshakeFailed |
Typeable HandshakeFailed |
Exception HandshakeFailed |

data ConnectionNotEstablished Source

Constructors

ConnectionNotEstablished |

Instances

Eq ConnectionNotEstablished |
Show ConnectionNotEstablished |
Typeable ConnectionNotEstablished |
Exception ConnectionNotEstablished |