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

License | BSD-style
Maintainer | Vincent Hanquez <vincent@snarc.org>
Stability | experimental
Portability | unknown
Safe Haskell | None
Language | Haskell98

Network.TLS

Contents

- Context configuration
- Context object
- Creating a context
- Initialisation and Termination of context
- High level API
- Crypto Key
- Compressions & Predefined compressions
- Ciphers & Predefined ciphers
- Versions
- Errors

Description

Synopsis

- data TLSParams = TLSParams {
  - pConnectVersion :: Version
  - pAllowedVersions :: [Version]
  - pCiphers :: [Cipher]
  - pCompressions :: [Compression]
  - pWantClientCert :: Bool
  - pUseSecureRenegotiation :: Bool
  - pCertificates :: [(X509, Maybe PrivateKey)]
  - pLogging :: TLSLogging
  - onCertificatesRecv :: [X509] -> IO TLSCertificateUsage
  }
- data TLSLogging = TLSLogging {
  - loggingPacketSent :: String -> IO ()
  - loggingPacketRecv :: String -> IO ()
  - loggingIOSent :: Bytes -> IO ()
  - loggingIORecv :: Header -> Bytes -> IO ()
  }
- data TLSCertificateUsage
  - = CertificateUsageAccept
  - | CertificateUsageReject TLSCertificateRejectReason
- data TLSCertificateRejectReason
  - = CertificateRejectExpired
  - | CertificateRejectRevoked
  - | CertificateRejectUnknownCA
  - | CertificateRejectOther String
- defaultParams :: TLSParams
- defaultLogging :: TLSLogging
- data TLSCtx a
- ctxConnection :: TLSCtx a -> a
- client :: (MonadIO m, CryptoRandomGen g) => TLSParams -> g -> Handle -> m (TLSCtx Handle)
- server :: (MonadIO m, CryptoRandomGen g) => TLSParams -> g -> Handle -> m (TLSCtx Handle)
- bye :: MonadIO m => TLSCtx c -> m ()
- handshake :: MonadIO m => TLSCtx c -> m Bool
- sendData :: MonadIO m => TLSCtx c -> ByteString -> m ()
- recvData :: MonadIO m => TLSCtx c -> m ByteString
- data PrivateKey = PrivRSA PrivateKey
- class CompressionC a where
  - compressionCID :: a -> Word8
  - compressionCDeflate :: a -> ByteString -> (a, ByteString)
  - compressionCInflate :: a -> ByteString -> (a, ByteString)
- data Compression = forall a . CompressionC a => Compression a
- nullCompression :: Compression
- data Cipher = Cipher {
  - cipherID :: Word16
  - cipherName :: String
  - cipherHash :: Hash
  - cipherBulk :: Bulk
  - cipherKeyExchange :: CipherKeyExchangeType
  - cipherMinVer :: Maybe Version
  }
- data Bulk = Bulk {
  - bulkName :: String
  - bulkKeySize :: Int
  - bulkIVSize :: Int
  - bulkBlockSize :: Int
  - bulkF :: BulkFunctions
  }
- data Version
  - = SSL2
  - | SSL3
  - | TLS10
  - | TLS11
  - | TLS12
- data TLSError
  - = Error_Misc String
  - | Error_Protocol (String, Bool, AlertDescription)
  - | Error_Certificate String
  - | Error_Random String
  - | Error_EOF
  - | Error_Packet String
  - | Error_Packet_Size_Mismatch (Int, Int)
  - | Error_Packet_unexpected String String
  - | Error_Packet_Parsing String
  - | Error_Internal_Packet_ByteProcessed Int Int Int
  - | Error_Unknown_Version Word8 Word8
  - | Error_Unknown_Type String

# Context configuration

data TLSParams

Constructors

TLSParams |

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.

pWantClientCert :: Bool

  request a certificate from client. use by server only.

pUseSecureRenegotiation :: Bool
pCertificates :: [(X509, Maybe PrivateKey)]

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

pLogging :: TLSLogging

  callback for logging

onCertificatesRecv :: [X509] -> IO TLSCertificateUsage

  callback to verify received cert chain.

Instances

Show TLSParams |

data TLSLogging

Constructors

TLSLogging |

Fields

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

data TLSCertificateUsage

Certificate Usage callback possible returns values.

Constructors

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

Instances

Eq TLSCertificateUsage |
Show TLSCertificateUsage |

data TLSCertificateRejectReason

Certificate and Chain rejection reason

Constructors

CertificateRejectExpired |
CertificateRejectRevoked |
CertificateRejectUnknownCA |
CertificateRejectOther String |

Instances

Eq TLSCertificateRejectReason |
Show TLSCertificateRejectReason |

defaultParams :: TLSParams

defaultLogging :: TLSLogging

# Context object

data TLSCtx a

A TLS Context is a handle augmented by tls specific state and parameters

ctxConnection :: TLSCtx a -> a

return the connection object associated with this context

# Creating a context

client :: (MonadIO m, CryptoRandomGen g) => TLSParams -> g -> Handle -> m (TLSCtx Handle)

Create a new Client context with a configuration, a RNG, and a Handle. It reconfigures the handle buffermode to noBuffering

server :: (MonadIO m, CryptoRandomGen g) => TLSParams -> g -> Handle -> m (TLSCtx Handle)

Create a new Server context with a configuration, a RNG, and a Handle. It reconfigures the handle buffermode to noBuffering

# Initialisation and Termination of context

bye :: MonadIO m => TLSCtx c -> 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 => TLSCtx c -> m Bool

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

# High level API

sendData :: MonadIO m => TLSCtx c -> ByteString -> m ()

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

recvData :: MonadIO m => TLSCtx c -> m ByteString

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

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

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

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

data Compression

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

Constructors

forall a . CompressionC a => Compression a |

Instances

Show Compression |

nullCompression :: Compression

default null compression

# Ciphers & Predefined ciphers

data Cipher

Cipher algorithm

Constructors

Cipher |

Fields

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

Instances

Eq Cipher |
Show Cipher |

data Bulk

Constructors

Bulk |

Fields

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

# Versions

data Version

Versions known to TLS

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

TLS12 is not yet 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_Random String |
Error_EOF |
Error_Packet String |
Error_Packet_Size_Mismatch (Int, Int) |
Error_Packet_unexpected String String |
Error_Packet_Parsing String |
Error_Internal_Packet_ByteProcessed Int Int Int |
Error_Unknown_Version Word8 Word8 |
Error_Unknown_Type String |

Instances

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