Safe Haskell	None

Network.Simple.TCP.TLS

Contents

Server side
Client side
- Client TLS Settings
Credentials
Utils
Low level support
Note to Windows users
Exports

Description

This module exports simple tools for establishing TLS-secured TCP connections, relevant to both the client side and server side of the connection.

This module re-exports some functions from the Network.Simple.TCP module in the network-simple package. Consider using that module directly if you need a similar API without TLS support.

Synopsis

Server side

serve Source

Arguments

:: ServerSettings	TLS settings.
-> HostPreference	Preferred host to bind.
-> ServiceName	Service port to bind.
-> ((Context, SockAddr) -> IO ())	Computation to run in a different thread once an incomming connection is accepted and a TLS-secured communication is established. Takes the TLS connection context and remote end address.
-> IO ()

Start a TLS-secured TCP server that accepts incoming connections and handles each of them concurrently, in different threads.

Any acquired network resources are properly closed and discarded when done or in case of exceptions. This function binds a listening socket, accepts an incoming connection, performs a TLS handshake and then safely closes the connection when done or in case of exceptions. You don't need to perform any of those steps manually.

Listening

listen

Arguments

:: HostPreference	Preferred host to bind.
-> ServiceName	Service port to bind.
-> ((Socket, SockAddr) -> IO r)	Computation taking the listening socket and the address it's bound to.
-> IO r

Bind a TCP listening socket and use it.

The listening socket is closed when done or in case of exceptions.

If you prefer to acquire and close the socket yourself, then use bindSock and the listen and sClose functions from Network.Socket instead.

Note: maxListenQueue is tipically 128, which is too small for high performance servers. So, we use the maximum between maxListenQueue and 2048 as the default size of the listening queue. The NoDelay and ReuseAddr options are set on the socket.

Accepting

accept Source

Arguments

:: ServerSettings	TLS settings.
-> Socket	Listening and bound socket.
-> ((Context, SockAddr) -> IO b)	Computation to run in a different thread once an incomming connection is accepted and a TLS-secured communication is established. Takes the TLS connection context and remote end address.
-> IO b

Accepts a single incomming TLS-secured TCP connection and use it.

A TLS handshake is performed immediately after establishing the TCP connection.

The connection is properly closed when done or in case of exceptions. If you need to manage the lifetime of the connection resources yourself, then use acceptTls instead.

acceptFork Source

Arguments

:: ServerSettings	TLS settings.
-> Socket	Listening and bound socket.
-> ((Context, SockAddr) -> IO ())	Computation to run in a different thread once an incomming connection is accepted and a TLS-secured communication is established. Takes the TLS connection context and remote end address.
-> IO ThreadId

Like accept, except it uses a different thread to performs the TLS handshake and run the given computation.

Server TLS Settings

data ServerSettings Source

Abstract type representing the configuration settings for a TLS server.

Use makeServerSettings to obtain your ServerSettings value, and updateServerParams to update it.

makeServerSettings Source

Arguments

:: Credential	Server credential.
-> Maybe CertificateStore	CAs used to verify the client certificate. If specified, then a valid client certificate will be expected during on handshake.
-> ServerSettings

Make default ServerSettings.

The following TLS settings are used by default:

Supported versions: TLS10, TLS11, TLS12.
Supported cipher suites for TLS10: In decreasing order of preference: cipher_AES256_SHA256, cipher_AES256_SHA1, cipher_AES128_SHA256, cipher_AES128_SHA1, cipher_RC4_128_SHA1, cipher_RC4_128_MD5. The cipher suite preferred by the client is used.
Supported cipher suites for TLS11 and TLS12: In decreasing order of preference: cipher_AES256_SHA256, cipher_AES256_SHA1, cipher_AES128_SHA256, cipher_AES128_SHA1. The cipher suite preferred by the client is used.

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

Update advanced TLS server configuration Params. See the Network.TLS module for details.

serverParams :: Functor f => (Params -> f Params) -> ServerSettings -> f ServerSettings Source

A Lens into the TLS server configuration Params. See the Network.TLS and the lens package for details.

Client side

connect Source

Arguments

:: ClientSettings	TLS settings.
-> HostName	Server hostname.
-> ServiceName	Server service port.
-> ((Context, SockAddr) -> IO r)	Computation to run after establishing TLS-secured TCP connection to the remote server. Takes the TLS connection context and remote end address.
-> IO r

Connect to a TLS-secured TCP server and use the connection

A TLS handshake is performed immediately after establishing the TCP connection.

The connection is properly closed when done or in case of exceptions. If you need to manage the lifetime of the connection resources yourself, then use connectTls instead.

Client TLS Settings

data ClientSettings Source

Abstract type representing the configuration settings for a TLS client.

Use makeClientSettings or getDefaultClientSettings to obtain your ClientSettings value.

makeClientSettings Source

Arguments

:: [Credential]	Credentials to provide to the server, if requested. The first one is used in case we can't choose one based on information provided by the server.
-> Maybe HostName	Explicit Server Name Identification (SNI).
-> CertificateStore	CAs used to verify the server certificate. Use `getSystemCertificateStore` to obtain the operating system's defaults.
-> ClientSettings

Make defaults ClientSettings.

The following TLS settings are used by default:

Supported versions: TLS10, TLS11, TLS12.
Version reported during ClientHello: TLS10.
Supported cipher suites: In decreasing order of preference: cipher_AES256_SHA256, cipher_AES256_SHA1, cipher_AES128_SHA256, cipher_AES128_SHA1, cipher_RC4_128_SHA1, cipher_RC4_128_MD5.

getDefaultClientSettings :: IO ClientSettings Source

Get the system default ClientSettings.

See makeClientSettings for the for the default TLS settings used.

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

Update advanced TLS client configuration Params. See the Network.TLS module for details.

clientParams :: Functor f => (Params -> f Params) -> ClientSettings -> f ClientSettings Source

A Lens into the TLS client configuration Params. See the Network.TLS and the lens package for details.

Credentials

data Credential Source

Primary certificate, private key and the rest of the certificate chain.

Constructors

Credential !X509 !PrivateKey [X509]

Instances

Show Credential

credentialToCertList :: Credential -> [(X509, Maybe PrivateKey)]Source

Convert client Credential to the format expected by pCertificates.

Utils

recv :: Context -> IO (Maybe ByteString)Source

Receives decrypted bytes from the given Context. Returns Nothing on EOF.

Up to 16384 decrypted bytes will be received at once. The TLS connection is automatically renegotiated if a ClientHello message is received.

send :: Context -> ByteString -> IO ()Source

Encrypts the given strict ByteString and sends it through the Context.

Low level support

connectTls :: ClientSettings -> HostName -> ServiceName -> IO (Context, SockAddr)Source

Estalbishes a TCP connection to a remote server and returns a TLS Context configured on top of it using the given ClientSettings. The remote end address is also returned.

Prefer to use connect if you will be used the obtained Context within a limited scope.

You need to call handshake on the resulting Context before using it for communication purposes, and bye afterwards. The useTls or useTlsThenCloseFork functions can perform those steps for you.

acceptTls :: ServerSettings -> Socket -> IO (Context, SockAddr)Source

Accepts an incoming TCP connection and returns a TLS Context configured on top of it using the given ServerSettings. The remote end address is also returned.

Prefer to use accept if you will be used the obtained Context within a limited scope.

You need to call handshake on the resulting Context before using it for communication purposes, and bye afterwards. The useTls or useTlsThenCloseFork functions can perform those steps for you.

useTls :: ((Context, SockAddr) -> IO a) -> (Context, SockAddr) -> IO aSource

Perform a TLS handshake on the given Context, then perform the given action and at last say bye, even in case of exceptions.

This function discards ResourceVanished exceptions that will happen when trying to say bye if the remote end has done it before.

useTlsThenCloseFork :: ((Context, SockAddr) -> IO ()) -> (Context, SockAddr) -> IO ThreadId Source

Similar to useTls, except it performs the all the IO actions safely in a new thread and closes the connection backend after using it. Use this instead of forking useTls yourself.

This function discards ResourceVanished exceptions that will happen when trying to close the connection backend if the remote end has done it before.

Note to Windows users

If you are running Windows, then you must call withSocketsDo, just once, right at the beginning of your program. That is, change your program's main function from:

 main = do
   print "Hello world"
   -- rest of the program...

To:

 main = withSocketsDo $ do
   print "Hello world"
   -- rest of the program...

If you don't do this, your networking code won't work and you will get many unexpected errors at runtime. If you use an operating system other than Windows then you don't need to do this, but it is harmless to do it, so it's recommended that you do for portability reasons.

withSocketsDo :: IO a -> IO a

On Windows operating systems, the networking subsystem has to be initialised using withSocketsDo before any networking operations can be used. eg.

 main = withSocketsDo $ do {...}

Although this is only strictly necessary on Windows platforms, it is harmless on other platforms, so for portability it is good practice to use it all the time.

Exports

data HostPreference

Preferred host to bind.

Constructors

HostAny	Any available host.
HostIPv4	Any available IPv4 host.
HostIPv6	Any available IPv6 host.
Host HostName	An explicit host name.

Instances

Eq HostPreference
Ord HostPreference
Read HostPreference
Show HostPreference
IsString HostPreference	The following special values are recognized: `` means `HostAny` `4` means `HostIPv4` `*6` means `HostIPv6` Any other string is `Host`