Safe Haskell | None |
---|
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.
- serve :: ServerSettings -> HostPreference -> ServiceName -> ((Context, SockAddr) -> IO ()) -> IO ()
- listen :: HostPreference -> ServiceName -> ((Socket, SockAddr) -> IO r) -> IO r
- accept :: ServerSettings -> Socket -> ((Context, SockAddr) -> IO b) -> IO b
- acceptFork :: ServerSettings -> Socket -> ((Context, SockAddr) -> IO ()) -> IO ThreadId
- data ServerSettings
- makeServerSettings :: Credential -> Maybe CertificateStore -> ServerSettings
- updateServerParams :: (Params -> Params) -> ServerSettings -> ServerSettings
- serverParams :: Functor f => (Params -> f Params) -> ServerSettings -> f ServerSettings
- connect :: ClientSettings -> HostName -> ServiceName -> ((Context, SockAddr) -> IO r) -> IO r
- data ClientSettings
- makeClientSettings :: [Credential] -> Maybe HostName -> CertificateStore -> ClientSettings
- getDefaultClientSettings :: IO ClientSettings
- updateClientParams :: (Params -> Params) -> ClientSettings -> ClientSettings
- clientParams :: Functor f => (Params -> f Params) -> ClientSettings -> f ClientSettings
- data Credential = Credential !X509 !PrivateKey [X509]
- credentialToCertList :: Credential -> [(X509, Maybe PrivateKey)]
- recv :: Context -> IO (Maybe ByteString)
- send :: Context -> ByteString -> IO ()
- connectTls :: ClientSettings -> HostName -> ServiceName -> IO (Context, SockAddr)
- acceptTls :: ServerSettings -> Socket -> IO (Context, SockAddr)
- useTls :: ((Context, SockAddr) -> IO a) -> (Context, SockAddr) -> IO a
- useTlsThenCloseFork :: ((Context, SockAddr) -> IO ()) -> (Context, SockAddr) -> IO ThreadId
- data HostPreference
Server side
:: 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
:: 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
:: 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.
:: 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.
:: 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
andTLS12
-
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 -> ServerSettingsSource
Update advanced TLS server configuration Params
.
See the Network.TLS module for details.
serverParams :: Functor f => (Params -> f Params) -> ServerSettings -> f ServerSettingsSource
A Lens
into the TLS server configuration Params
.
See the Network.TLS and the lens
package for details.
Client side
:: 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.
:: [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 |
-> 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 ClientSettingsSource
Get the system default ClientSettings
.
See makeClientSettings
for the for the default TLS settings used.
updateClientParams :: (Params -> Params) -> ClientSettings -> ClientSettingsSource
Update advanced TLS client configuration Params
.
See the Network.TLS module for details.
clientParams :: Functor f => (Params -> f Params) -> ClientSettings -> f ClientSettingsSource
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.
Credential !X509 !PrivateKey [X509] |
credentialToCertList :: Credential -> [(X509, Maybe PrivateKey)]Source
Convert client Credential
to the format expected by pCertificates
.
Utils
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.
useTlsThenCloseFork :: ((Context, SockAddr) -> IO ()) -> (Context, SockAddr) -> IO ThreadIdSource
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.
Exports
data HostPreference
Preferred host to bind.
HostAny | Any available host. |
HostIPv4 | Any available IPv4 host. |
HostIPv6 | Any available IPv6 host. |
Host HostName | An explicit host name. |
Eq HostPreference | |
Ord HostPreference | |
Read HostPreference | |
Show HostPreference | |
IsString HostPreference | The following special values are recognized: |