Plug

v1.8.0

Plug v1.8.0 Plug.SSL View Source

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-proto

If your Plug application is behind a proxy that handles HTTPS, you will need to tell Plug to parse the proper protocol from the x-forwarded-proto header. This can be done using the :rewrite_on option:

plug Plug.SSL, rewrite_on: [:x_forwarded_proto]

The command above will effectively change the value of conn.scheme to the one sent in x-forwarded-proto.

Since rewriting the scheme based on x-forwarded-proto can open up security vulnerabilities, only provide the option above if:

  • your app is behind a proxy
  • your proxy strips x-forwarded-proto headers from all incoming requests
  • your proxy sets the x-forwarded-proto and sends it to Plug

Plug Options

  • :rewrite_on - rewrites the scheme to https based on the given headers
  • :hsts - a boolean on enabling HSTS or not, defaults to true
  • :expires - seconds to expires for HSTS, defaults to 7884000 (three months)
  • :preload - a boolean to request inclusion on the HSTS preload list (for full set of required flags, see: Chromium HSTS submission site), defaults to false
  • :subdomains - a boolean on including subdomains or not in HSTS, defaults to false
  • :exclude - exclude the given hosts from redirecting to the https scheme. Defaults to ["localhost"]
  • :host - a new host to redirect to if the request's scheme is http, defaults to conn.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 be false 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".

Link to this section Summary

Functions

call(conn, arg)

Plug pipeline callback

configure(options)

Configures and validates the options given to the :ssl application

init(opts)

Plug initialization callback

Link to this section Functions

Link to this function

call(conn, arg) View Source

Plug pipeline callback.

Link to this function

configure(options) View Source 
configure(Keyword.t()) :: {:ok, Keyword.t()} | {: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.

For further information, please refer to the adapter documentation and the HTTPS Guide.

Cipher Suites

To simplify configuration of TLS defaults Plug 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.

Link to this function

init(opts) View Source

Plug initialization callback.