NAME
Plack::Middleware::XSRFBlock - Block XSRF Attacks with minimal changes
to your app
VERSION
version 0.0.5
SYNOPSIS
The simplest way to use the plugin is:
use Plack::Builder;
my $app = sub { ... };
builder {
enable 'XSRFBlock';
$app;
}
You may also over-ride any, or all of these values:
builder {
enable 'XSRFBlock',
parameter_name => 'xsrf_token',
cookie_name => 'PSGI-XSRF-Token',
cookie_options => {},
cookie_expiry_seconds => (3 * 60 * 60),
token_per_request => 0,
meta_tag => undef,
header_name => undef,
blocked => sub {
return [ $status, $headers, $body ]
},
;
$app;
}
DESCRIPTION
This middleware blocks XSRF. You can use this middleware without any
modifications to your application.
OPTIONS
parameter_name (default: 'xsrf_token')
The name assigned to the hidden form input containing the token.
cookie_name (default: 'PSGI-XSRF-Token')
The name of the cookie used to store the token value.
cookie_options (default: {})
Extra cookie options to be set with the cookie. This is useful for
things like setting "HttpOnly" to tell the browser to only send it
with HTTP requests, and "Secure" on the cookie to force the cookie
to only be sent on SSL requests.
builder {
enable 'XSRFBlock', cookie_options => { secure => 1, httponly => 1 };
}
token_per_request (default: 0)
If this is true a new token is assigned for each request made.
This may make your application more secure, or less susceptible to
double-submit issues.
meta_tag (default: undef)
If this is set, use the value as the name of the meta tag to add to
the head section of output pages.
This is useful when you are using javascript that requires access to
the token value for making AJAX requests.
header_name (default: undef)
If this is set, use the value as the name of the response heaer that
the token can be sent in. This is useful for non-browser based
submissions; e.g. Javascript AJAX requests.
blocked (default: undef)
If this is set it should be a PSGI application that is returned
instead of the default HTTP_FORBIDDEN(403) and text/plain response.
This could be useful if you'd like to perform some action that's
more in keeping with your application - e.g. return a styled error
page.
ERRORS
The module emits various errors based on the cause of the XSRF detected.
The messages will be of the form "XSRF detected [reason]"
form field missing
The request was submitted but there was no value submitted in the
form field specified by <C$self->parameter_name> [default:
xsrf_token]
xsrf token missing
The application has been configured to accept an 'X-' header and no
token value was found in either the header or a suitable form field.
[default: undef]
cookie missing
There is no cookie with the name specified by "$self-"cookie_name>
[default: PSGI-XSRF-Token]
invalid token
The cookie token and form value were both submitted correctly but
the values do not match.
EXPLANATION
This module is similar in nature and intention to
Plack::Middleware::CSRFBlock but implements the xSRF prevention in a
different manner.
The solution implemented in this module is based on a CodingHorror
article - Preventing CSRF and XSRF Attacks
<http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-attac
ks.html>.
The driving comment behind this implementation is from the Felten and
Zeller paper
<https://www.eecs.berkeley.edu/~daw/teaching/cs261-f11/reading/csrf.pdf>
:
When a user visits a site, the site should generate a (cryptographically
strong) pseudorandom value and set it as a cookie on the user's machine.
The site should require every form submission to include this pseudorandom
value as a form value and also as a cookie value. When a POST request is
sent to the site, the request should only be considered valid if the form
value and the cookie value are the same. When an attacker submits a form
on behalf of a user, he can only modify the values of the form. An
attacker cannot read any data sent from the server or modify cookie
values, per the same-origin policy. This means that while an attacker can
send any value he wants with the form, he will be unable to modify or read
the value stored in the cookie. Since the cookie value and the form value
must be the same, the attacker will be unable to successfully submit a
form unless he is able to guess the pseudorandom value.
What's wrong with Plack::Middleware::CSRFBlock?
Plack::Middleware::CSRFBlock is a great module. It does a great job of
preventing CSRF behaviour with minimal effort.
However when we tried to use it uses the session to store information -
which works well most of the time but can cause issues with session
timeouts or removal (for any number of valid reasons) combined with
logging (back) in to the application in another tab (so as not to
interfere with the current screen/tab state).
Trying to modify the existing module to provide the extra functionality
and behaviour we decided worked better for our use seemed too far
reaching to try to force into the existing module.
FURTHER READING
* Preventing CSRF and XSRF Attacks
<http://www.codinghorror.com/blog/2008/10/preventing-csrf-and-xsrf-a
ttacks.html>
* Preventing Cross Site Request Forgery (CSRF)
<https://www.golemtechnologies.com/articles/csrf>
* Cross-Site Request Forgeries: Exploitation and Prevention [PDF]
<https://www.eecs.berkeley.edu/~daw/teaching/cs261-f11/reading/csrf.
pdf>
* Cross-Site Request Forgery (CSRF) Prevention Cheat Sheet
<https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF)_P
revention_Cheat_Sheet>
SEE ALSO
Plack::Middleware::CSRFBlock, Plack::Middleware, Plack
AUTHOR
Chisel <chisel@chizography.net>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Chisel Wright.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
CONTRIBUTORS
* Chisel <chisel.wright@net-a-porter.com>
* Chisel Wright <chisel@chizography.net>
* Matthew Ryall <matt.ryall@gmail.com>
* Sebastian Willert <willert@gmail.com>
* William Wolf <throughnothing@gmail.com>