warp-tls-3.4.13: HTTP over TLS support for Warp via the TLS package

Safe Haskell | None
Language | Haskell2010

Network.Wai.Handler.WarpTLS

Contents

- Runner
- Settings
- Smart constructors
  - From files
  - From memory
  - From references
  - Dynamically retrieved
- Accessors
- Exception
- Low-level

Description

HTTP over TLS support for Warp via the TLS package.

If HTTP/2 is negotiated by ALPN, HTTP/2 over TLS is used. Otherwise HTTP/1.1 over TLS is used.

Support for SSL is now obsoleted.

Synopsis

- runTLS :: TLSSettings -> Settings -> Application -> IO ()
- runTLSSocket :: TLSSettings -> Settings -> Socket -> Application -> IO ()
- data TLSSettings
- defaultTlsSettings :: TLSSettings
- tlsSettings :: FilePath -> FilePath -> TLSSettings
- tlsSettingsChain :: FilePath -> [FilePath] -> FilePath -> TLSSettings
- tlsSettingsMemory :: ByteString -> ByteString -> TLSSettings
- tlsSettingsChainMemory :: ByteString -> [ByteString] -> ByteString -> TLSSettings
- tlsSettingsRef :: IORef ByteString -> IORef ByteString -> TLSSettings
- tlsSettingsChainRef :: IORef ByteString -> [IORef ByteString] -> IORef ByteString -> TLSSettings
- data CertSettings
- tlsSettingsSni :: (Maybe HostName -> IO Credentials) -> TLSSettings
- tlsCredentials :: TLSSettings -> Maybe Credentials
- tlsLogging :: TLSSettings -> Logging
- tlsAllowedVersions :: TLSSettings -> [Version]
- tlsCiphers :: TLSSettings -> [Cipher]
- tlsWantClientCert :: TLSSettings -> Bool
- tlsServerHooks :: TLSSettings -> ServerHooks
- tlsServerDHEParams :: TLSSettings -> Maybe DHParams
- tlsSessionManagerConfig :: TLSSettings -> Maybe Config
- tlsSessionManager :: TLSSettings -> Maybe SessionManager
- onInsecure :: TLSSettings -> OnInsecure
- data OnInsecure
  - = DenyInsecure ByteString
  - | AllowInsecure
- data WarpTLSException
  - = InsecureConnectionDenied
  - | ClientClosedConnectionPrematurely
- attachConn :: SockAddr -> Context -> IO (Connection, Transport)

# Runner

runTLS :: TLSSettings -> Settings -> Application -> IO () Source #

Running `Application` with `TLSSettings` and `Settings`.

runTLSSocket :: TLSSettings -> Settings -> Socket -> Application -> IO () Source #

Running `Application` with `TLSSettings` and `Settings` using specified `Socket`.

# Settings

data TLSSettings Source #

Settings for WarpTLS.

defaultTlsSettings :: TLSSettings Source #

Default `TLSSettings`. Use this to create `TLSSettings` with the field record name (aka accessors).

# Smart constructors

## From files

tlsSettings Source #

Arguments

:: FilePath | Certificate file
-> FilePath | Key file
-> TLSSettings |

A smart constructor for `TLSSettings` based on `defaultTlsSettings`.

tlsSettingsChain Source #

Arguments

:: FilePath | Certificate file
-> [FilePath] | Chain certificate files
-> FilePath | Key file
-> TLSSettings |

A smart constructor for `TLSSettings` that allows specifying chain certificates based on `defaultTlsSettings`.

Since 3.0.3

## From memory

tlsSettingsMemory Source #

Arguments

:: ByteString | Certificate bytes
-> ByteString | Key bytes
-> TLSSettings |

A smart constructor for `TLSSettings`, but uses in-memory representations of the certificate and key based on `defaultTlsSettings`.

Since 3.0.1

tlsSettingsChainMemory Source #

Arguments

:: ByteString | Certificate bytes
-> [ByteString] | Chain certificate bytes
-> ByteString | Key bytes
-> TLSSettings |

A smart constructor for `TLSSettings`, but uses in-memory representations of the certificate and key based on `defaultTlsSettings`.

Since 3.0.3

## From references

tlsSettingsRef Source #

Arguments

:: IORef ByteString | Reference to certificate bytes
-> IORef ByteString | Reference to key bytes
-> TLSSettings |

Deprecated: This function was added to allow Warp to serve new certificates without restarting, but it has always behaved the same as `tlsSettingsMemory`. It will be removed in the next major release. To retain existing behavior, swich to `tlsSettingsMemory`. To dynamically update credentials, see `tlsSettingsSni`.

A smart constructor for `TLSSettings`, but uses references to in-memory representations of the certificate and key based on `defaultTlsSettings`.

Since: 3.3.0

tlsSettingsChainRef Source #

Arguments

:: IORef ByteString | Reference to certificate bytes
-> [IORef ByteString] | Reference to chain certificate bytes
-> IORef ByteString | Reference to key bytes
-> TLSSettings |

Deprecated: This function was added to allow Warp to serve new certificates without restarting, but it has always behaved the same as `tlsSettingsChainMemory`. It will be removed in the next major release. To retain existing behavior, swich to `tlsSettingsChainMemory`. To dynamically update credentials, see `tlsSettingsSni`.

A smart constructor for `TLSSettings`, but uses references to in-memory representations of the certificate and key based on `defaultTlsSettings`.

Since: 3.3.0

data CertSettings Source #

Determines where to load the certificate, chain certificates, and key from.

#### Instances

Instances details

Show CertSettings Source # |
Instance details Defined in Network.Wai.Handler.WarpTLS.Internal Methods showsPrec :: Int -> CertSettings -> ShowS Source # show :: CertSettings -> String Source # showList :: [CertSettings] -> ShowS Source #

## Dynamically retrieved

tlsSettingsSni :: (Maybe HostName -> IO Credentials) -> TLSSettings Source #

Smart constructor for TLS settings that obtains its credentials during Server Name Indication. Can be used to return different credentials depending on the hostname but also to retrieve dynamically updated credentials from an IORef. Credentials can be loaded from PEM-encoded chain and key files using `credentialLoadX509`.

Since: 3.4.13

# Accessors

tlsCredentials :: TLSSettings -> Maybe Credentials Source #

Specifying `Credentials` directly. If this value is specified, other fields such as `certFile` are ignored.

Since 3.2.12

tlsLogging :: TLSSettings -> Logging Source #

The level of logging to turn on.

Default: `defaultLogging`.

Since 1.4.0

tlsAllowedVersions :: TLSSettings -> [Version] Source #

The TLS versions this server accepts.

Since 1.4.2

tlsCiphers :: TLSSettings -> [Cipher] Source #

The TLS ciphers this server accepts.

Since 1.4.2

tlsWantClientCert :: TLSSettings -> Bool Source #

Whether or not to demand a certificate from the client. If this is set to True, you must handle received certificates in a server hook or all connections will fail.

    >>> tlsWantClientCert defaultTlsSettings
    False

Since 3.0.2

tlsServerHooks :: TLSSettings -> ServerHooks Source #

The server-side hooks called by the tls package, including actions to take when a client certificate is received. See the Network.TLS module for details.

Default: defaultServerHooks

Since 3.0.2

tlsServerDHEParams :: TLSSettings -> Maybe DHParams Source #

Configuration for ServerDHEParams more function lives in `crypton` package

Default: Nothing

Since 3.2.2

tlsSessionManagerConfig :: TLSSettings -> Maybe Config Source #

Configuration for in-memory TLS session manager. If Nothing, `noSessionManager` is used. Otherwise, an in-memory TLS session manager is created according to `Config`.

Default: Nothing

Since 3.2.4

tlsSessionManager :: TLSSettings -> Maybe SessionManager Source #

Specifying `SessionManager` directly. If this value is specified, `tlsSessionManagerConfig` is ignored.

Since 3.2.12

onInsecure :: TLSSettings -> OnInsecure Source #

Do we allow insecure connections with this server as well?

    >>> onInsecure defaultTlsSettings
    DenyInsecure "This server only accepts secure HTTPS connections."

Since 1.4.0

data OnInsecure Source #

An action when a plain HTTP comes to HTTP over TLS/SSL port.

Constructors

DenyInsecure ByteString |
AllowInsecure |

#### Instances

Instances details

Show OnInsecure Source # |
Instance details Defined in Network.Wai.Handler.WarpTLS.Internal Methods showsPrec :: Int -> OnInsecure -> ShowS Source # show :: OnInsecure -> String Source # showList :: [OnInsecure] -> ShowS Source #

# Exception

data WarpTLSException Source #

Constructors

InsecureConnectionDenied |
ClientClosedConnectionPrematurely |

#### Instances

Instances details

Exception WarpTLSException Source # |
Instance details Defined in Network.Wai.Handler.WarpTLS Methods toException :: WarpTLSException -> SomeException Source # fromException :: SomeException -> Maybe WarpTLSException Source # displayException :: WarpTLSException -> String Source # backtraceDesired :: WarpTLSException -> Bool Source #
Show WarpTLSException Source # |
Instance details Defined in Network.Wai.Handler.WarpTLS Methods showsPrec :: Int -> WarpTLSException -> ShowS Source # show :: WarpTLSException -> String Source # showList :: [WarpTLSException] -> ShowS Source #

# Low-level

attachConn :: SockAddr -> Context -> IO (Connection, Transport) Source #

Get Connection and Transport for a TLS connection that is already did the handshake. @since 3.4.7