/usr/share/perl5/Plack/Middleware/README.pod is in libplack-middleware-csrfblock-perl 0.10-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 | =pod
=encoding UTF-8
=head1 NAME
Plack::Middleware::CSRFBlock - Block CSRF Attacks with minimal changes to your app
=head1 VERSION
version 0.10
=head1 SYNOPSIS
use Plack::Builder;
my $app = sub { ... }
builder {
enable 'Session';
enable 'CSRFBlock';
$app;
}
=head1 DESCRIPTION
This middleware blocks CSRF. You can use this middleware without any modifications
to your application, in most cases. Here is the strategy:
=over 4
=item output filter
When the application response content-type is "text/html" or
"application/xhtml+xml", this inserts a hidden input tag that contains a token
string into C<form>s in the response body. For example, when the application
response body is:
<html>
<head>
<title>input form</title>
</head>
<body>
<form action="/api" method="post">
<input type="text" name="email" /><input type="submit" />
</form>
</html>
This becomes:
<html>
<head>
<title>input form</title>
</head>
<body>
<form action="/api" method="post"><input type="hidden" name="SEC" value="0f15ba869f1c0d77" />
<input type="text" name="email" /><input type="submit" />
</form>
</html>
This affects C<form> tags with C<method="post">, case insensitive.
It is possible to add an optional meta tag by setting C<meta_tag> to a defined
value. The 'name' attribute of the HTML tag will be set to the value of
C<meta_tag>. For the previous example, when C<meta_tag> is set to
'csrf_token', the output will be:
<html>
<head><meta name="csrf_token" content="0f15ba869f1c0d77"/>
<title>input form</title>
</head>
<body>
<form action="/api" method="post"><input type="hidden" name="SEC" value="0f15ba869f1c0d77" />
<input type="text" name="email" /><input type="submit" />
</form>
</html>
=item input check
For every POST requests, this module checks the C<X-CSRF-Token> header first,
then C<POST> input parameters. If the correct token is not found in either,
then a 403 Forbidden is returned by default.
Supports C<application/x-www-form-urlencoded> and C<multipart/form-data> for
input parameters, but any C<POST> will be validated with the C<X-CSRF-Token>
header. Thus, every C<POST> will have to have either the header, or the
appropriate form parameters in the body.
=item javascript
This module can be used easily with javascript by having your javascript
provide the C<X-CSRF-Token> with any ajax C<POST> requests it makes. You can
get the C<token> in javascript by getting the value of the C<csrftoken> C<meta>
tag in the page <head>. Here is sample code that will work for C<jQuery>:
$(document).ajaxSend(function(e, xhr, options) {
var token = $("meta[name='csrftoken']").attr("content");
xhr.setRequestHeader("X-CSRF-Token", token);
});
This will include the X-CSRF-Token header with any C<AJAX> requests made from
your javascript.
=back
=head1 OPTIONS
use Plack::Builder;
my $app = sub { ... }
builder {
enable 'Session';
enable 'CSRFBlock',
parameter_name => 'csrf_secret',
token_length => 20,
session_key => 'csrf_token',
blocked => sub {
[302, [Location => 'http://www.google.com'], ['']];
},
onetime => 0,
;
$app;
}
=over 4
=item parameter_name (default:"SEC")
Name of the input tag for the token.
=item meta_tag (default:undef)
Name of the C<meta> tag added to the C<head> tag of
output pages. The content of this C<meta> tag will be
the token value. The purpose of this tag is to give
javascript access to the token if needed for AJAX requests.
If this attribute is not explicitly set the meta tag will not
be included.
=item header_name (default:"X-CSRF-Token")
Name of the HTTP Header that the token can be sent in.
This is useful for sending the header for Javascript AJAX requests,
and this header is required for any post request that is not
of type C<application/x-www-form-urlencoded> or C<multipart/form-data>.
=item token_length (default:16);
Length of the token string. Max value is 40.
=item session_key (default:"csrfblock.token")
This middleware uses L<Plack::Middleware::Session> for token storage. this is
the session key for that.
=item blocked (default:403 response)
The application called when CSRF is detected.
Note: This application can read posted data, but DO NOT use them!
=item onetime (default:FALSE)
If this is true, this middleware uses B<onetime> token, that is, whenever
client sent collect token and this middleware detect that, token string is
regenerated.
This makes your applications more secure, but in many cases, is too strict.
=back
=head1 SEE ALSO
L<Plack::Middleware::Session>
=head1 AUTHORS
=over 4
=item *
Rintaro Ishizaki <rintaro@cpan.org>
=item *
William Wolf <throughnothing@gmail.com>
=item *
Matthew Phillips <mattp@cpan.org>
=back
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by the Authors of Plack-Middleware-CSRFBlock.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut
|