/ 
Catalyst-Plugin-RequireSSL-0.07
River stage zero No dependents
/ Catalyst::Plugin::RequireSSL

NAME

Catalyst::Plugin::RequireSSL - Force SSL mode on select pages

SYNOPSIS

# in MyApp.pm
use Catalyst qw/
    RequireSSL
/;
__PACKAGE__->config(
    require_ssl => {
        https => 'secure.mydomain.com',
        http => 'www.mydomain.com',
        remain_in_ssl => 0,
        no_cache => 0,
        detach_on_redirect => 1,
    },
);
__PACKAGE__->setup;


# in any controller methods that should be secured
$c->require_ssl;

DESCRIPTION

Note: This module is considered to be deprecated for most purposes. Consider using Catalyst::ActionRole::RequireSSL instead.

Use this plugin if you wish to selectively force SSL mode on some of your web pages, for example a user login form or shopping cart.

Simply place $c->require_ssl calls in any controller method you wish to be secured.

This plugin will automatically disable itself if you are running under the standalone HTTP::Daemon Catalyst server. A warning message will be printed to the log file whenever an SSL redirect would have occurred.

WARNINGS

If you utilize different servers or hostnames for non-SSL and SSL requests, and you rely on a session cookie to determine redirection (i.e for a login page), your cookie must be visible to both servers. For more information, see the documentation for the Session plugin you are using.

CONFIGURATION

Configuration is optional. You may define the following configuration values:

https => $ssl_host

If your SSL domain name is different from your non-SSL domain, set this value.

http => $non_ssl_host

If you have set the https value above, you must also set the hostname of your non-SSL server.

remain_in_ssl

If you'd like your users to remain in SSL mode after visiting an SSL-required page, you can set this option to 1. By default, this option is disabled and users will be redirected back to non-SSL mode as soon as possible.

no_cache

If you have a wildcard certificate you will need to set this option if you are using multiple domains on one instance of Catalyst.

detach_on_redirect

By default $c->require_ssl only calls $c->response->redirect but does not stop request processing (so it returns and subsequent statements are run). This is probably not what you want. If you set this option to a true value $c->require_ssl will call $c->detach when it redirects.

METHODS

require_ssl

Call require_ssl in any controller method you wish to be secured.

$c->require_ssl;

The browser will be redirected to the same path on your SSL server. POST requests are never redirected.

allow_ssl

Call allow_ssl in any controller method you wish to access both in SSL and non-SSL mode.

$c->allow_ssl;

The browser will not be redirected, independently of whether the request was made to the SSL or non-SSL server.

setup

Disables this plugin if running under an engine which does not support SSL.

finalize

Performs the redirect to SSL url if required.

KNOWN ISSUES

When viewing an SSL-required page that uses static files served from the Static plugin, the static files are redirected to the non-SSL path.

In order to get the correct behaviour where static files are not redirected, you should use the Static::Simple plugin or always serve static files directly from your web server.

SEE ALSO

Catalyst, Catalyst::ActionRole::RequireSSL, Catalyst::Plugin::Static::Simple

AUTHOR

Andy Grundman, <andy@hybridized.org>

CONTRIBUTORS

Simon Elliott <simon@browsing.co.uk> (support for wildcards)

COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.