.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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" ''
. ds C`
. ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\" ========================================================================
.\"
.IX Title "README 3pm"
.TH README 3pm "2016-10-29" "perl v5.24.1" "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"
Plack::Middleware::CSRFBlock \- Block CSRF Attacks with minimal changes to your app
.SH "VERSION"
.IX Header "VERSION"
version 0.10
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Plack::Builder;
\&
\& my $app = sub { ... }
\&
\& builder {
\& enable \*(AqSession\*(Aq;
\& enable \*(AqCSRFBlock\*(Aq;
\& $app;
\& }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This middleware blocks \s-1CSRF.\s0 You can use this middleware without any modifications
to your application, in most cases. Here is the strategy:
.IP "output filter" 4
.IX Item "output filter"
When the application response content-type is \*(L"text/html\*(R" or
\&\*(L"application/xhtml+xml\*(R", this inserts a hidden input tag that contains a token
string into \f(CW\*(C`form\*(C'\fRs in the response body. For example, when the application
response body is:
.Sp
.Vb 9
\&
\&
\& input form
\&
\&
\&
\&
.Ve
.Sp
This becomes:
.Sp
.Vb 9
\&
\&
\& input form
\&
\&
\&
\&
.Ve
.Sp
This affects \f(CW\*(C`form\*(C'\fR tags with \f(CW\*(C`method="post"\*(C'\fR, case insensitive.
.Sp
It is possible to add an optional meta tag by setting \f(CW\*(C`meta_tag\*(C'\fR to a defined
value. The 'name' attribute of the \s-1HTML\s0 tag will be set to the value of
\&\f(CW\*(C`meta_tag\*(C'\fR. For the previous example, when \f(CW\*(C`meta_tag\*(C'\fR is set to
\&'csrf_token', the output will be:
.Sp
.Vb 9
\&
\&
\& input form
\&
\&
\&
\&
.Ve
.IP "input check" 4
.IX Item "input check"
For every \s-1POST\s0 requests, this module checks the \f(CW\*(C`X\-CSRF\-Token\*(C'\fR header first,
then \f(CW\*(C`POST\*(C'\fR input parameters. If the correct token is not found in either,
then a 403 Forbidden is returned by default.
.Sp
Supports \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR and \f(CW\*(C`multipart/form\-data\*(C'\fR for
input parameters, but any \f(CW\*(C`POST\*(C'\fR will be validated with the \f(CW\*(C`X\-CSRF\-Token\*(C'\fR
header. Thus, every \f(CW\*(C`POST\*(C'\fR will have to have either the header, or the
appropriate form parameters in the body.
.IP "javascript" 4
.IX Item "javascript"
This module can be used easily with javascript by having your javascript
provide the \f(CW\*(C`X\-CSRF\-Token\*(C'\fR with any ajax \f(CW\*(C`POST\*(C'\fR requests it makes. You can
get the \f(CW\*(C`token\*(C'\fR in javascript by getting the value of the \f(CW\*(C`csrftoken\*(C'\fR \f(CW\*(C`meta\*(C'\fR
tag in the page . Here is sample code that will work for \f(CW\*(C`jQuery\*(C'\fR:
.Sp
.Vb 4
\& $(document).ajaxSend(function(e, xhr, options) {
\& var token = $("meta[name=\*(Aqcsrftoken\*(Aq]").attr("content");
\& xhr.setRequestHeader("X\-CSRF\-Token", token);
\& });
.Ve
.Sp
This will include the X\-CSRF-Token header with any \f(CW\*(C`AJAX\*(C'\fR requests made from
your javascript.
.SH "OPTIONS"
.IX Header "OPTIONS"
.Vb 1
\& use Plack::Builder;
\&
\& my $app = sub { ... }
\&
\& builder {
\& enable \*(AqSession\*(Aq;
\& enable \*(AqCSRFBlock\*(Aq,
\& parameter_name => \*(Aqcsrf_secret\*(Aq,
\& token_length => 20,
\& session_key => \*(Aqcsrf_token\*(Aq,
\& blocked => sub {
\& [302, [Location => \*(Aqhttp://www.google.com\*(Aq], [\*(Aq\*(Aq]];
\& },
\& onetime => 0,
\& ;
\& $app;
\& }
.Ve
.ie n .IP "parameter_name (default:""\s-1SEC""\s0)" 4
.el .IP "parameter_name (default:``\s-1SEC''\s0)" 4
.IX Item "parameter_name (default:SEC)"
Name of the input tag for the token.
.IP "meta_tag (default:undef)" 4
.IX Item "meta_tag (default:undef)"
Name of the \f(CW\*(C`meta\*(C'\fR tag added to the \f(CW\*(C`head\*(C'\fR tag of
output pages. The content of this \f(CW\*(C`meta\*(C'\fR tag will be
the token value. The purpose of this tag is to give
javascript access to the token if needed for \s-1AJAX\s0 requests.
If this attribute is not explicitly set the meta tag will not
be included.
.ie n .IP "header_name (default:""X\-CSRF\-Token"")" 4
.el .IP "header_name (default:``X\-CSRF\-Token'')" 4
.IX Item "header_name (default:X-CSRF-Token)"
Name of the \s-1HTTP\s0 Header that the token can be sent in.
This is useful for sending the header for Javascript \s-1AJAX\s0 requests,
and this header is required for any post request that is not
of type \f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR or \f(CW\*(C`multipart/form\-data\*(C'\fR.
.IP "token_length (default:16);" 4
.IX Item "token_length (default:16);"
Length of the token string. Max value is 40.
.ie n .IP "session_key (default:""csrfblock.token"")" 4
.el .IP "session_key (default:``csrfblock.token'')" 4
.IX Item "session_key (default:csrfblock.token)"
This middleware uses Plack::Middleware::Session for token storage. this is
the session key for that.
.IP "blocked (default:403 response)" 4
.IX Item "blocked (default:403 response)"
The application called when \s-1CSRF\s0 is detected.
.Sp
Note: This application can read posted data, but \s-1DO NOT\s0 use them!
.IP "onetime (default:FALSE)" 4
.IX Item "onetime (default:FALSE)"
If this is true, this middleware uses \fBonetime\fR token, that is, whenever
client sent collect token and this middleware detect that, token string is
regenerated.
.Sp
This makes your applications more secure, but in many cases, is too strict.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Plack::Middleware::Session
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Rintaro Ishizaki
.IP "\(bu" 4
William Wolf
.IP "\(bu" 4
Matthew Phillips
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014 by the Authors of Plack-Middleware-CSRFBlock.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.