HMAC Based CSRF Protection

The hmac mode is available for applications that do not support J2EE sessions. The HMAC protection provides a stateless approach to generating and validating CSRF tokens. It should be noted that this mode requires additional integration steps in order to generate and configure the key used to perform the HMAC signatures. Additionally, the developer will need to modify application code in order to provide a user specific seed to include in the token generation. This will ensure that the generated CSRF tokens are user specific.

Keyczar Key Generation
The following steps detail how to create a Keyczar keyfile and generate a primary signing key. The Keyczar key file location can be changed to the location of your choice. The file system access to this file should be restricted as much as possible, however, you must ensure that the application server has read access to the file.

1. Download latest KeyczarTool standalone command line tool: https://code.google.com/p/keyczar/downloads/list
2. ```mkdir /opt/keyczar_anticsrf_signkey````
3. java -jar KeyczarTool create --location=/opt/keyczar_anticsrf_signkey --purpose=sign
4. java -jar KeyczarTool-0.71g-090613.jar addkey --location=/opt/keyczar_anticsrf_signkey --status=primary

The reason Keyczar was chosen to perform HMAC validation is due to its support for Key Rotation. This allows developers to promote, demote and revoke signing keys over time in order to provide added security in the event a key is compromised.

HMAC Specific Configuration Options

<anticsrf>
..snip..
    <hmac_settings>
        <keyfile>/opt/keyczar_anticsrf_signkey</keyfile>
        <sitewide_timeout>5</sitewide_timeout>
        <seed_attribute_name>userseed</seed_attribute_name>

        <urlspecific>
            <url timeout="1">/URLSpecificServlet</url>
        </urlspecific>
    </hmac_settings>
</anticsrf>

Config Option	Description	Default Value
keyfile	The file path to the Keyczar keyfile containing the HMAC signing key. This option is required when using the HMAC protection mode.	N/A
sitewide_timeout	The timeout value (in minutes) for site wide CSRF tokens. Any token older than the specified value will be denied by the library.	30
seed_attribute_name	The attribute name within the HttpServletRequest object that will stored the user specific seed for generating the HMAC Signatures.	userseed
urlspecific	The listing of application endpoints that require URL specific tokens to be specific. Optionally, the a custom "timeout" attribute can be used for each URL. This allows for very short timeouts to be set on sensitive URLs and provide a token that is very close to a one time use token. If no "timeout" is set, the token is utilize the configuration sitewide expiration value.	N/A

Setting User Seed
This is a very important step in order to make the tokens generated by the library become tied to a user's identity. This is the primary security control that allows this solution properly mitigate CSRF vulnerabilities. The user seed does not need to be cryptographically secure and can be any value that is unique to the authenticated user (username, userid, etc).

The application developer can set the UserSeed using the following method:

CSRFProtection csrfProtection = CSRFProtectionFactory.getCSRFProtection();
csrfProtection.setUserSeed((HttpServletRequest)request, <specified UserSeed>);

The user seed should ideally be set within the application's authentication filter or module. This will allow for the user seed to be set consistently on all authenticated requests.


The UserSeed must be set before a CSRF Token is generated. If utilizing the CSRFFilter class, it must be configured to execute after the request is authenticated and the user identity is set as the CSRF Token seed. The application's web.xml configuration should be modified accordingly in order to ensure the CSRFFilter occurs later in the FilterChain than any authentication J2EE filters. Refer to the API Documentation if a more customized integration is required.