README

   1 NAME
   2     Catalyst::Plugin::RequireSSL - Force SSL mode on select pages
   3
   4 SYNOPSIS
   5         # in MyApp.pm
   6         use Catalyst qw/
   7             RequireSSL
   8         /;
   9         __PACKAGE__->config(
  10             require_ssl => {
  11                 https => 'secure.mydomain.com',
  12                 http => 'www.mydomain.com',
  13                 remain_in_ssl => 0,
  14                 no_cache => 0,
  15                 detach_on_redirect => 1,
  16             },
  17         );
  18         __PACKAGE__->setup;
  19
  20
  21         # in any controller methods that should be secured
  22         $c->require_ssl;
  23
  24 DESCRIPTION
  25     Note: This module is considered to be deprecated for most purposes.
  26     Consider using Catalyst::ActionRole::RequireSSL instead.
  27
  28     Use this plugin if you wish to selectively force SSL mode on some of
  29     your web pages, for example a user login form or shopping cart.
  30
  31     Simply place $c->require_ssl calls in any controller method you wish to
  32     be secured.
  33
  34     This plugin will automatically disable itself if you are running under
  35     the standalone HTTP::Daemon Catalyst server. A warning message will be
  36     printed to the log file whenever an SSL redirect would have occurred.
  37
  38 WARNINGS
  39     If you utilize different servers or hostnames for non-SSL and SSL
  40     requests, and you rely on a session cookie to determine redirection (i.e
  41     for a login page), your cookie must be visible to both servers. For more
  42     information, see the documentation for the Session plugin you are using.
  43
  44 CONFIGURATION
  45     Configuration is optional. You may define the following configuration
  46     values:
  47
  48         https => $ssl_host
  49
  50     If your SSL domain name is different from your non-SSL domain, set this
  51     value.
  52
  53         http => $non_ssl_host
  54
  55     If you have set the https value above, you must also set the hostname of
  56     your non-SSL server.
  57
  58         remain_in_ssl
  59
  60     If you'd like your users to remain in SSL mode after visiting an
  61     SSL-required page, you can set this option to 1. By default, this option
  62     is disabled and users will be redirected back to non-SSL mode as soon as
  63     possible.
  64
  65         no_cache
  66
  67     If you have a wildcard certificate you will need to set this option if
  68     you are using multiple domains on one instance of Catalyst.
  69
  70         detach_on_redirect
  71
  72     By default "$c->require_ssl" only calls "$c->response->redirect" but
  73     does not stop request processing (so it returns and subsequent
  74     statements are run). This is probably not what you want. If you set this
  75     option to a true value "$c->require_ssl" will call "$c->detach" when it
  76     redirects.
  77
  78 METHODS
  79   require_ssl
  80     Call require_ssl in any controller method you wish to be secured.
  81
  82         $c->require_ssl;
  83
  84     The browser will be redirected to the same path on your SSL server. POST
  85     requests are never redirected.
  86
  87   allow_ssl
  88     Call allow_ssl in any controller method you wish to access both in SSL
  89     and non-SSL mode.
  90
  91         $c->allow_ssl;
  92
  93     The browser will not be redirected, independently of whether the request
  94     was made to the SSL or non-SSL server.
  95
  96   setup
  97     Disables this plugin if running under an engine which does not support
  98     SSL.
  99
 100   finalize
 101     Performs the redirect to SSL url if required.
 102
 103 KNOWN ISSUES
 104     When viewing an SSL-required page that uses static files served from the
 105     Static plugin, the static files are redirected to the non-SSL path.
 106
 107     In order to get the correct behaviour where static files are not
 108     redirected, you should use the Static::Simple plugin or always serve
 109     static files directly from your web server.
 110
 111 SEE ALSO
 112     Catalyst, Catalyst::ActionRole::RequireSSL,
 113     Catalyst::Plugin::Static::Simple
 114
 115 AUTHOR
 116     Andy Grundman, <andy@hybridized.org>
 117
 118 CONTRIBUTORS
 119     Simon Elliott <simon@browsing.co.uk> (support for wildcards)
 120
 121 COPYRIGHT
 122     This program is free software, you can redistribute it and/or modify it
 123     under the same terms as Perl itself.
 124