NAME

Plack::Middleware::RedirectSSL - force all requests to use in-/secure connections

SYNOPSIS

 # in app.psgi
 use Plack::Builder;
 
 builder {
     enable 'RedirectSSL';
     $app;
 };

DESCRIPTION

This middleware intercepts requests using either the http or https scheme and redirects them to the same URI under respective other scheme.

CONFIGURATION OPTIONS

ssl

Specifies the direction of redirects. If true, requests using http will be redirected to https. If false, requests using https will be redirected to plain http.

Defaults to true if not specified during construction.

hsts_header

Specifies an arbitrary string value for the Strict-Transport-Security header. If false, no such header will be sent.

hsts_policy

Specifies a value to pass to "render_sts_policy" and updates the hsts_header option with the returned value.

 enable 'RedirectSSL', hsts_policy => { include_subdomains => 1 };

Defaults to an HSTS policy with default values, which is a max-age of 26 weeks and no other directives.

hsts

Use of this option is discouraged.

Specifies a max-age value for the hsts_policy option, preserving all other existing hsts_policy directives, if any. If undef, uses a max-age of 26 weeks. If otherwise false, sets hsts_policy to undef. (If you really want a max-age value of 0, use '00', '0E0' or '0 but true'.)

FUNCTIONS

render_sts_policy

Takes either a hash reference containing an HSTS policy or undef, and returns the corresponding Strict-Transport-Security header value.

 my $policy = { include_subdomains => 1 };
 printf "Strict-Transport-Security: %s\n", render_sts_policy $policy;
 # Strict-Transport-Security: max-age=15724800; includeSubDomains

As a side effect, validates the policy and updates the hash with the ultimate value of every directive after computing defaults.

 use Data::Dumper; local $Data::Dumper::Terse = 1;
 print +Dumper $policy;
 # {
 #   'max_age' => 15724800,
 #   'include_subdomains' => 1,
 #   'preload' => ''
 # }

The following directives are supported:

max_age

Integer value for the max-age directive.

If missing or undefined, it will normally default to 26 weeks.

But if the preload directive is true, it will default to 365 days and may not be set to any smaller value.

If 0 (which unpublishes a previous HSTS policy), no other directives may be set.

include_subdomains

Boolean; whether to include the includeSubDomains directive.

If missing or undefined, it will normally default to false.

But if the preload directive is true, it will defaults to true and may not be set to false.

preload

Boolean; whether to include the preload directive.

SEE ALSO

• Plack::Middleware::ReverseProxy

  If your PSGI application runs behind a reverse proxy that unwraps SSL connections then you will need to put this middleware in front of RedirectSSL.

• RFC 6797, HTTP Strict Transport Security

• HSTS preload

  Specification of the preload directive and submission form for inclusion into the Google Chrome preload list (also used by most other browsers)

AUTHOR

Aristotle Pagaltzis <pagaltzis@gmx.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Aristotle Pagaltzis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.