tls-1.1.2: 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
  - = BulkNoneF
  - | 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

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

Constructors

Client ClientParams |
Server ServerParams |

data ClientParams

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

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

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

data Logging

Constructors

Logging |

Fields

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

data Measurement

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

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

Certificate and Chain rejection reason

Constructors

CertificateRejectExpired |
CertificateRejectRevoked |
CertificateRejectUnknownCA |
CertificateRejectOther String |

Instances

Eq CertificateRejectReason |
Show CertificateRejectReason |

defaultParamsClient :: Params

defaultParamsServer :: Params

defaultLogging :: Logging

data MaxFragmentEnum

Constructors

MaxFragment512 |
MaxFragment1024 |
MaxFragment2048 |
MaxFragment4096 |

Instances

Eq MaxFragmentEnum |
Show MaxFragmentEnum |

type HashAndSignatureAlgorithm = (HashAlgorithm, SignatureAlgorithm)

data HashAlgorithm

Constructors

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

Instances

Eq HashAlgorithm |
Show HashAlgorithm |
TypeValuable HashAlgorithm |

data SignatureAlgorithm

Constructors

SignatureAnonymous |
SignatureRSA |
SignatureDSS |
SignatureECDSA |
SignatureOther Word8 |

Instances

Eq SignatureAlgorithm |
Show SignatureAlgorithm |
TypeValuable SignatureAlgorithm |

data CertificateType

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

# raw types

data ProtocolType

Constructors

ProtocolType_ChangeCipherSpec |
ProtocolType_Alert |
ProtocolType_Handshake |
ProtocolType_AppData |
ProtocolType_DeprecatedHandshake |

Instances

Eq ProtocolType |
Show ProtocolType |
TypeValuable ProtocolType |

data Header

Constructors

Header ProtocolType Version Word16 |

Instances

Eq Header |
Show Header |

# Session

type SessionID = ByteString

A session ID

data SessionData

Session data to resume

Constructors

SessionData |

Fields

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

class SessionManager a where

A session manager

Methods

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

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

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

used when a session is established.

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

used when a session is invalidated

Instances

SessionManager NoSessionManager |

data NoSessionManager

Constructors

NoSessionManager |

Instances

SessionManager NoSessionManager |

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

Set a new session manager in a parameters structure.

# Backend abstraction

data Backend

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

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

ctxConnection :: Context -> Backend

return the backend object associated with this context

# Creating a context

contextNew

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

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

contextClose :: Context -> IO ()

# deprecated type aliases

type TLSParams = Params

type TLSLogging = Logging

type TLSCertificateUsage = CertificateUsage

type TLSCertificateRejectReason = CertificateRejectReason

type TLSCtx = Context

# deprecated values

defaultParams :: Params

# Initialisation and Termination of context

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

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

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)

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

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

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

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.

# Crypto Key

data PrivateKey

Constructors

PrivRSA PrivateKey |

Instances

Show PrivateKey |

# Compressions & Predefined compressions

class CompressionC a where

supported compression algorithms need to be part of this class

Methods

compressionCID :: a -> CompressionID

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

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

Instances

CompressionC NullCompression |

data Compression

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

Compression identification

nullCompression :: Compression

default null compression

data NullCompression

This is the default compression which is a NOOP.

Instances

CompressionC NullCompression |

# member redefined for the class abstraction

compressionID :: Compression -> CompressionID

return the associated ID for this algorithm

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

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

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

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

# helper

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

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

Constructors

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

data CipherKeyExchangeType

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

Constructors

Bulk |

Fields

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

data Hash

Constructors

Hash |

Fields

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

data Cipher

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

Cipher identification

cipherKeyBlockSize :: Cipher -> Int

type Key = ByteString

type IV = ByteString

cipherExchangeNeedMoreData :: CipherKeyExchangeType -> Bool

# Versions

data Version

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

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 |
MonadError TLSError TLSSt |

data KxError

Constructors

RSAError Error |

Instances

Show KxError |

data AlertDescription

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

# Exceptions

data Terminated

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

Constructors

HandshakeFailed TLSError |

Instances

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

data ConnectionNotEstablished

Constructors

ConnectionNotEstablished |

Instances

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