.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.19)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::RequireSSL 3pm"
.TH CGI::Application::Plugin::RequireSSL 3pm "2011-11-07" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Application::Plugin::RequireSSL \- Force SSL in specified pages or modules
.SH "VERSION"
.IX Header "VERSION"
Version 0.04
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CGI::Application::Plugin::RequireSSL;
\&
\&    sub login_form :RequireSSL {
\&        my $self = shift;
\&        # etc
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
CGI::Application::Plugin::RequireSSL allows individual run modes or
whole modules to be protected by \s-1SSL\s0. If a standard \s-1HTTP\s0 request is
received, you can specify whether an error is raised or if the request
should be redirected to the \s-1HTTPS\s0 equivalent \s-1URL\s0.
.SH "EXPORT"
.IX Header "EXPORT"
Exported methods:
    config_requiressl, mode_redirect
.SH "USAGE"
.IX Header "USAGE"
.SS "run mode-level protection"
.IX Subsection "run mode-level protection"
run mode protection is specified by the RequireSSL attribute after the
method name:
.PP
.Vb 3
\&    sub process_login :RequireSSL {
\&        my $self = shift;
\&    }
.Ve
.SS "Module-level protection"
.IX Subsection "Module-level protection"
You can protect a complete module by setting the 'require_ssl'
parameter in your instance script:
.PP
.Vb 5
\&    use MyApp;
\&    my $webapp = MyApp\->new(
\&        PARAMS => {require_ssl => 1}
\&    );
\&    $webapp\->run();
.Ve
.SS "Redirecting to a protected \s-1URL\s0."
.IX Subsection "Redirecting to a protected URL."
By default, an error is raised if a request is made to a protected
run mode or module using \s-1HTTP\s0. However, you can specify that the request
is redirected to the \s-1HTTPS\s0 url by setting the rewrite_to_ssl parameter
as long as the requested method is not \s-1POST:\s0
.PP
.Vb 3
\&    my $webapp = MyApp\->new(
\&        PARAMS => {rewrite_to_ssl => 1}
\&    );
.Ve
.SS "Turning off checks."
.IX Subsection "Turning off checks."
If you need to turn off checks, simply set the ignore_check parameter
when configuring the plugin (see \*(L"config_requiressl\*(R" below).
.SS "Reverting to \s-1HTTP\s0"
.IX Subsection "Reverting to HTTP"
Once a successful request is made to a protected run mode or module, subsequent
requests to a non-protected run mode or module will revert to using \s-1HTTP\s0.
To prevent this from happening, set the parameter keep_in_ssl in the
configuration
(see \*(L"config_requiressl\*(R" below)
.SH "METHODS"
.IX Header "METHODS"
.SS "config_requiressl"
.IX Subsection "config_requiressl"
Optionally configure the plugin in your cgiapp_init method
.PP
.Vb 4
\&    $self\->config_requiressl(
\&        keep_in_ssl => 0,
\&        ignore_check => 0,
\&    )
.Ve
.PP
Valid parameters are:
.IP "\(bu" 4
keep_in_ssl \- if set, all subsequent requests following one to a
protected run mode or module will be via \s-1HTTPS\s0.
.IP "\(bu" 4
ignore_check \- ignore \s-1SSL\s0 schecking. This is useful if your
application is deployed in an environment that doesn't support \s-1SSL\s0.
.SS "mode_redirect"
.IX Subsection "mode_redirect"
This is a run mode that will be automatically called if the request should
be redirected to the equivalent \s-1HTTP\s0 or \s-1HTTPS\s0 \s-1URL\s0. You should not call it
directly.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dan Horne, \f(CW\*(C`<dhorne at cpan.org>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-cgi\-application\-plugin\-requiressl at rt.cpan.org\*(C'\fR, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI\-Application\-Plugin\-RequireSSL <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-RequireSSL>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "CAVEAT"
.IX Header "CAVEAT"
This module been tested under the FastCGI persistent environment, but not under
mod_perl. The author would apprecaute feedback from anyone who is able to
test with that environment.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc CGI::Application::Plugin::RequireSSL
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
http://annocpan.org/dist/CGI\-Application\-Plugin\-RequireSSL <http://annocpan.org/dist/CGI-Application-Plugin-RequireSSL>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
http://cpanratings.perl.org/d/CGI\-Application\-Plugin\-RequireSSL <http://cpanratings.perl.org/d/CGI-Application-Plugin-RequireSSL>
.IP "\(bu" 4
\&\s-1RT:\s0 \s-1CPAN\s0's request tracker
.Sp
http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI\-Application\-Plugin\-RequireSSL <http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Application-Plugin-RequireSSL>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
http://search.cpan.org/dist/CGI\-Application\-Plugin\-RequireSSL <http://search.cpan.org/dist/CGI-Application-Plugin-RequireSSL>
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
.IP "\(bu" 4
Users of the CGI::Application wiki (http://www.cgi\-app.org) who requested
this module.
.IP "\(bu" 4
Andy Grundman \- I stole the idea of the keep_in_ssl parameter from his
Catalyst::Plugin::RequireSSL module
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2007 Dan Horne, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.