NAME

       WWW::CSRF - Generate and check tokens to protect against CSRF attacks

SYNOPSIS

        use WWW::CSRF qw(generate_csrf_token check_csrf_token CSRF_OK);

       Generate a token to add as a hidden <input> in all HTML forms:

        my $csrf_token = generate_csrf_token($username, "s3kr1t");

       Then, in any action with side effects, retrieve that form field and check it with:

        my $status = check_csrf_token($username, "s3kr1t", $csrf_token);
        die "Wrong CSRF token" unless ($status == CSRF_OK);

COPYRIGHT

       Copyright 2013 Steinar H. Gunderson.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

DESCRIPTION

       This module generates tokens to help protect against a website attack known as Cross-Site
       Request Forgery (CSRF, also known as XSRF).  CSRF is an attack where an attacker fools a
       browser into make a request to a web server for which that browser will automatically
       include some form of credentials (cookies, cached HTTP Basic authentication, etc.), thus
       abusing the web server's trust in the user for malicious use.

       The most common CSRF mitigation is sending a special, hard-to-guess token with every
       request, and then require that any request that is not idempotent (i.e., has side effects)
       must be accompanied with such a token.  This mitigation depends critically on the fact
       that while an attacker can easily make the victim's browser make a request, the browser
       security model (same-origin policy, or SOP for short) prevents third-party sites from
       reading the results of that request.

       CSRF tokens should have at least the following properties:

       •   They should be hard-to-guess, so they should be signed with some key known only to the
           server.

       •   They should be dependent on the authenticated identity, so that one user cannot use
           its own tokens to impersonate another user.

       •   They should not be the same for every request, or an attack known as BREACH can use
           HTTP compression to gradually deduce more and more of the token.

       •   They should contain an (authenticated) timestamp, so that if an attacker manages to
           learn one token, he or she cannot impersonate a user indefinitely.

       WWW::CSRF simplifies the (simple, but tedious) work of creating and verifying such tokens.

       Note that resources that are protected against CSRF should also be protected against a
       different attack known as clickjacking.  There are many defenses against clickjacking
       (which ideally should be combined), but a good start is sending a "X-Frame-Options" HTTP
       header set to "DENY" or "SAMEORIGIN".  See the Wikipedia article on clickjacking
       <http://en.wikipedia.org/wiki/Clickjacking> for more information.

       This module provides the following functions:

       generate_csrf_token($id, $secret, \%options)
           This routine generates a CSRF token to send out to already authenticated users.
           (Unauthenticated users generally need no CSRF protection, as there are no credentials
           to impersonate.)

           $id is the identity you wish to authenticate; usually, this would be a user name of
           some sort.

           $secret is the secret key authenticating the token.  This should be protected in the
           same matter you would protect other server-side secrets, e.g. database passwords--if
           this leaks out, an attacker can generate CSRF tokens at will.

           The keys in %options are relatively esoteric and need generally not be set, but
           currently supported are:

           •   "Time", for overriding the time value added to the token.  If this is not set, the
               value of "time()" is used.

           •   "Random", for controlling the random masking value used to protect against the
               BREACH attack.  If set, it must be exactly 20 random bytes; if not, these bytes
               are generated with a call to Bytes::Random::Secure.

           The returned CSRF token is in a text-only form suitable for inserting into a HTML form
           without further escaping (assuming you did not send in strange things to the "Time"
           option).

       check_csrf_token($id, $secret, $csrf_token, \%options)
           This routine checks the integrity and age of the a token generated by
           "generate_csrf_token".  The values of $id and $secret correspond to the same
           parameters given to "generate_csrf_token", and $csrf_token is the token to verify.
           Also, you can set one or more of the following options in %options:

           •   "Time", for overriding the time value used to check the age of the token. If this
               is not set, the value of "time()" is used.

           •   "MaxAge", for setting a maximum age for the CSRF token in seconds.  If this is
               negative, no age checking is performed, which is not recommended.  The default
               value is a week, or 604800 seconds.

           This routine returns one of the following constants:

           •   "CSRF_OK": The token is verified correct.

           •   "CSRF_EXPIRED": The token has an expired timestamp, but is otherwise valid.

           •   "CSRF_INVALID_SIGNATURE": The token is not properly authenticated; either it was
               generated using the wrong secret, for the wrong user, or it has been tampered with
               in-transit.

           •   "CSRF_MALFORMED_TOKEN": The token is not in the correct format.

           In general, you should only allow the requested action if "check_csrf_token" returns
           "CSRF_OK".

           Note that you are allowed to call "check_csrf_token" multiple times with e.g.
           different secrets.  This is useful in the case of key rollover, where you change the
           secret for new tokens, but want to continue accepting old tokens for some time to
           avoid disrupting operations.

SEE ALSO

       Wikipedia has an article with more information on CSRF:

         L<http://en.wikipedia.org/wiki/Cross-site_request_forgery>