Adrian Citu's Blog

Goal of this article

The goal of this article is to present an implementation of the “double submit cookie” pattern used to mitigate the Cross Site Request Forgery (CSRF) attacks. The proposed implementation is a Java filter plus a few auxiliary classes and it is (obviously) suitable for projects using the Java language as back-end technology.

Definition of CSRF and possible mitigations

In the case of a CSRF attack, the browser is tricked into making unauthorized requests on the victim’s behalf, without the victim’s knowledge. The general attack scenario contains the following steps:

the victim connects to the vulnerable web-site, so it have a real, authenticated session.

the hacker force the victim (usually using a spam/fishing email) to navigate to another (evil) web-site containing the CSRF attack.

when the victim browser execute the (evil) web-site page, the browser will execute a (fraudulent) request to the vulnerable web-site using the user authenticated session. The user is not aware at all of the fact that navigating on the (evil) web-site will trigger an action on the vulnerable web-site.

In order to mitigate the CSRF attacks the following techniques can be used:

verifying the same origin with standard headers; This technique consists in determining the origin the request is coming from (source origin) and determining the origin the request is going to (target origin).

synchronizer token pattern – an anti-CSRF token is created and stored in the user session and in a hidden field on subsequent form submits. At every submit the server checks the token from the session matches the one submitted from the form. Tomcat 6+ implements this pattern(for more infos please see CSRF Protection Filter) and also OWASP CSRFGuard project offers another implementation.

challenge/response pattern – the solution consists in forcing the user to enter a value known only to him in order to complete the action.

encrypted token pattern – when a user authenticates to a site, the site should generate a unique token comprised of the user’s ID, a timestamp value and a nonce, using a unique key available only on the server. The token is returned to the client and embedded into a hidden field. When the form is posted on server, the server decrypts the token and verifies that the use ID retrieved from the token matches the one from the session.

double-cookie submit pattern – this will be defined in the next paragraph.

Definition of “double submit cookie” pattern

When a user authenticates to a site, the site should generate a (cryptographically strong) pseudo-random value and set it as a cookie on the user’s machine separate from the session id. The server does not have to save this value in any way, that’s why this patterns is sometimes also called Stateless CSRF Defense.

The site then requires that every transaction request include this random value as a hidden form value (or other request parameter). A cross origin attacker cannot read any data sent from the server or modify cookie values, per the same-origin policy.

In the case of this mitigation technique the job of the client is very simple; just retrieve the CSRF cookie from the response and add it into a special header to all the requests:

Client workflow

The job of the server is a little more complex; create the CSRF cookie and for each request asking for a protected resource, check that the CSRF cookie and the CSRF header of the request are matching:

The filter can have 2 optional initialization parameters: csrfCookieName representing the name of the cookie that will store the CSRF token and csrfHeaderName representing the name of the HTTP header that will be also contains the CSRF token.

The default values for these parameters are “XSRF-TOKEN” for the csrfCookieName and “X-XSRF-TOKEN” for the csrhHeaderName, both of them being the default values that AngularJS is expecting to have in order to implement the CSRF protection.

The filter creates an instance of ExecutionContext class; this class is a simple POJO containing the initial HTTP request, the HTTP response, the CSRF cookies (if more than one cookie with the csrfCookieName is present) and implementation of the ResourceCheckerHook , TokenBuilderHook and ResponseBuilderHook .(see the next section for the meaning of this classes).

The filter check the status of the HTTP resource, that status can be:MUST_NOT_BE_PROTECTED, MUST_BE_PROTECTED_BUT_NO_COOKIE_ATTACHED,MUST_BE_PROTECTED_AND_COOKIE_ATTACHED (see ResourceStatus enum) using an instance of ResourceCheckerHook.

The TokenBuilderHook hook is used to generate the token that will be used to create the CSRF cookie. The default implementation is DefaultTokenBuilderHookImpl and it uses a call to UUID.randomUUID to fetch a token. The interface signature is the following one:

The hooks are instantiated inside the GenericCSRFStatelessFilter#init method using the ServiceLoader Java 6 loading facility. So if you want to use your implementation of one of the hooks then you have to create a META-INF/services directory that contains a text file whose name matches the fully-qualified interface class name of the hook that you want to replace.