Catalyst::Plugin::CSRFToken - Generate tokens to help prevent CSRF attacks
package MyApp; use Catalyst; # The default functionality of this plugin expects a method 'sessionid' which # is associated with the current user session. This method is provided by the # session plugin but you can provide your own or override 'default_csrf_session_id' # if you know what you are doing! MyApp->setup_plugins([qw/ Session Session::State::Cookie Session::Store::Cookie CSRFToken /]); MyApp->config( 'Plugin::CSRFToken' => { default_secret=>'changeme', auto_check_csrf_token => 1 } ); MyApp->setup; package MyApp::Controller::Root; use Moose; use MooseX::MethodAttributes; extends 'Catalyst::Controller'; sub login_form :Path(login_form) Args(0) { my ($self, $c) = @_; # A Basic manual check example if you leave 'auto_check_csrf_token' off (default) if($c->req->method eq 'POST') { Catalyst::Exception->throw(message => 'csrf_token failed validation') unless $c->check_csrf_token; } $c->stash(csrf_token => $c->csrf_token); # send a token to your view and make sure you # add it to your form as a hidden field }
This uses WWW::CSRF to generate hard to guess tokens tied to a give web session. You can generate a token and pass it to your view layer where it should be added to the form you are trying to process, typically as a hidden field called 'csrf_token' (althought you can change that in configuration if needed).
Its probably best to enable 'auto_check_csrf_token' true since that will automatically check all POST, bPUT and PATCH request (but of course if you do this you have to be sure to add the token to every single form. If you need to just use this on a few forms (for example you have a large legacy application and need to improve security in steps) you can roll your own handling via the check_csrf_token method as in the example given above.
check_csrf_token
This Plugin adds the following methods
This just returns base64 random string that is cryptographically secure and is generically useful for anytime you just need a random token. Default length is 48 but please note that the actual base64 length will be longer.
Generates a token for the current request path and user session and returns this string in a form suitable to put into an HTML form hidden field value. Accepts the following positional arguments:
This is a string of data which is somehow linked to the current user session. The default is to call the method 'default_csrf_session_id' which currently just returns the value of '$c->sessionid'. You can pass something here if you want a tigher scope (for example you want a token that is scoped to both the current user id and a given URL path).
Default is whatever you set the configuration value 'default_secret' to.
Return true or false depending on if the current request has a token which is valid. Accepts the following arguments in the form of a hash:
The token to check. Default behavior is to invoke method find_csrf_token_in_request which looks in the HTTP request header and body parameters for the token. Set this to validate a specific token.
find_csrf_token_in_request
It should match whatever you passed to csrf_token for the request token you are trying to validate.
csrf_token
Default is whatever you set the configuration value 'default_secret' to. Allows you to specify a custom secret (it should match whatever you passed to csrf_token).
Defaults to whatever you set configuration value <max_age>. A value in seconds that measures how long a token is considered 'not expired'. I recommend setting this to as short a value as is reasonable for your users to linger on a form page.
Example:
$c->check_csrf_token(max_age=>(60*10)); # Don't accept a token that is older than 10 minutes.
NOTE: If the token
Returns true if the token is invalid. This is just the inverse of 'check_csrf_token' and it accepts the same arguments.
Return true if the last checked token was considered expired based on the arguments used to check it. Useful if you are writing custom checking code that wants to return a different error if the token was well formed but just too old. Throws an exception if you haven't actually checked a token.
Creates a token that is saved in the session. Unlike 'csrf_token' this token is not crytographically signed so intead its saved in the user session and can only be used once. You might prefer this approach for classic HTML forms while the other approach could be better for API applications where you don't want the overhead of a user session (or where you'd like the client to be able to open multiply connections at once.
Checks a single_use_csrf_token. Accepts the token to check but defaults to getting it from the request if not provided.
This plugin permits the following configurations keys
String that is used in part to generate the token to help ensure its hard to guess.
Default to 3600 seconds (one hour). This is the length of time before the generated token is considered expired. One hour is probably too long. You should set it to the shortest time reasonable.
Defaults to 'csrf_token'. The Body param key we look for the token.
Defaults to false. When set to true we automatically do a check for all POST, PATCH and PUT method requests and if the check fails we delegate handling in the following way:
If the current controller does a method called 'handle_failed_csrf_token_check' we invoke that passing the current context.
Else if the application class does a method called 'handle_failed_csrf_token_check' we invoke that instead.
Failing either of those we just throw an exception and set a rational message body (403 Forbidden: Bad CSRF token). In all cases if there's a CSRF error we skip the 'dispatch' phase so none of your actions will run, including any global 'end' actions.
John Napiorkowski <jnapiork@cpan.org>
Copyright (c) 2023 the above named AUTHOR
You may distribute this code under the same terms as Perl itself.
To install Catalyst::Plugin::CSRFToken, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Catalyst::Plugin::CSRFToken
CPAN shell
perl -MCPAN -e shell install Catalyst::Plugin::CSRFToken
For more information on module installation, please visit the detailed CPAN module installation guide.