View Source Plug.SSL (Plug v1.16.1)
A plug to force SSL connections and enable HSTS.
If the scheme of a request is https
, it'll add a strict-transport-security
header to enable HTTP Strict Transport Security by default.
Otherwise, the request will be redirected to a corresponding location
with the https
scheme by setting the location
header of the response.
The status code will be 301 if the method of conn
is GET
or HEAD
,
or 307 in other situations.
Besides being a Plug, this module also provides conveniences for configuring
SSL. See configure/1
.
x-forwarded-*
If your Plug application is behind a proxy that handles HTTPS, you may
need to tell Plug to parse the proper protocol from the x-forwarded-*
header. This can be done using the :rewrite_on
option:
plug Plug.SSL, rewrite_on: [:x_forwarded_host, :x_forwarded_port, :x_forwarded_proto]
For further details refer to Plug.RewriteOn
.
Plug Options
:rewrite_on
- rewrites the given connection information based on the given headers:hsts
- a boolean on enabling HSTS or not, defaults totrue
:expires
- seconds to expires for HSTS, defaults to31_536_000
(1 year):preload
- a boolean to request inclusion on the HSTS preload list (for full set of required flags, see: Chromium HSTS submission site), defaults tofalse
:subdomains
- a boolean on including subdomains or not in HSTS, defaults tofalse
:exclude
- exclude the given hosts from redirecting to thehttps
scheme. Defaults to["localhost"]
. It may be set to a list of binaries or a tuple{module, function, args}
.:host
- a new host to redirect to if the request's scheme ishttp
, defaults toconn.host
. It may be set to a binary or a tuple{module, function, args}
that will be invoked on demand:log
- The log level at which this plug should log its request info. Default is:info
. Can befalse
to disable logging.
Port
It is not possible to directly configure the port in Plug.SSL
because
HSTS expects the port to be 443 for SSL. If you are not using HSTS and
want to redirect to HTTPS on another port, you can sneak it alongside
the host, for example: host: "example.com:443"
.
Excluded hosts tuple
Tuple {module, function, args}
can be passed to be invoked each time
the plug is checking whether to redirect host. Provided function needs
to receive at least one argument (host
).
For example, you may define it as:
plug Plug.SSL,
rewrite_on: [:x_forwarded_proto],
exclude: {__MODULE__, :excluded_host?, []}
where:
def excluded_host?(host) do
# Custom logic
end
Summary
Functions
Configures and validates the options given to the :ssl
application.
Functions
@spec configure([:ssl.tls_server_option()]) :: {:ok, [:ssl.tls_server_option()]} | {:error, String.t()}
Configures and validates the options given to the :ssl
application.
This function is often called internally by adapters, such as Cowboy, to validate and set reasonable defaults for SSL handling. Therefore Plug users are not expected to invoke it directly, rather you pass the relevant SSL options to your adapter which then invokes this.
Options
This function accepts all options defined
in Erlang/OTP :ssl
documentation.
Besides the options from :ssl
, this function adds on extra option:
:cipher_suite
- it may be:strong
or:compatible
, as outlined in the following section
Furthermore, it sets the following defaults:
secure_renegotiate: true
- to avoid certain types of man-in-the-middle attacksreuse_sessions: true
- for improved handshake performance of recurring connections
For a complete guide on HTTPS and best pratices, see our Plug HTTPS Guide.
Cipher Suites
To simplify configuration of TLS defaults, this function provides two preconfigured
options: cipher_suite: :strong
and cipher_suite: :compatible
. The Ciphers
chosen and related configuration come from the OWASP Cipher String Cheat
Sheet
We've made two modifications to the suggested config from the OWASP recommendations. First we include ECDSA certificates which are excluded from their configuration. Second we have changed the order of the ciphers to deprioritize DHE because of performance implications noted within the OWASP post itself. As the article notes "...the TLS handshake with DHE hinders the CPU about 2.4 times more than ECDHE".
The Strong cipher suite only supports tlsv1.2. Ciphers were based on the OWASP Group A+ and includes support for RSA or ECDSA certificates. The intention of this configuration is to provide as secure as possible defaults knowing that it will not be fully compatible with older browsers and operating systems.
The Compatible cipher suite supports tlsv1, tlsv1.1 and tlsv1.2. Ciphers were based on the OWASP Group B and includes support for RSA or ECDSA certificates. The intention of this configuration is to provide as secure as possible defaults that still maintain support for older browsers and Android versions 4.3 and earlier
For both suites we've specified certificate curves secp256r1, ecp384r1 and secp521r1. Since OWASP doesn't prescribe curves we've based the selection on Mozilla's recommendations
The cipher suites were last updated on 2018-JUN-14.