Examples of hirondelle.web4j.security.CsrfFilter

kipedia.org/wiki/Cross-site_request_forgery'>Cross Site Request Forgery (CSRF).

Please see the package overview for important information regarding CSRF attacks, and security in general.

This filter maintains various items needed to protect against CSRF attacks. It acts both as a pre-processor and as a post-processor. The behavior of this class is controlled by detecting two important events:

the creation of new sessions (which does not necessarily imply a successful user login has also occured)
a successful user login (which does imply a session has also been created)

Pre-processing

When a new session is detected (but not necessarily a user login), then this class will do the following :

calculate a random form-source id, and place it in session scope, under the key {@link #FORM_SOURCE_ID_KEY}. This value is difficult to guess.
wrap the response in a custom wrapper, to implement the post-processing performed by this filter (see below)

In addition, if a new user login is detected, then this class will do the following :

if there is any 'old' form-source id, place it in session scope as well, under the key {@link #PREVIOUS_FORM_SOURCE_ID_KEY}. The 'old' form-source id is simply the form-source id used in the immediately preceding session for the same user.
place in session scope an object which will store the form-source id when the session expires or is invalidated, under the key {@link #FORM_SOURCE_DAO_KEY}.

The above behavior of this class upon user login requires interaction with your database. It's configured in web.xml using two items : FormSourceIdRead and FormSourceIdWrite. These two items are {@link hirondelle.web4j.database.SqlId} references. They tell this class which SQL statements to use when reading and writing form-source ids to the database. As usual, these {@link SqlId} items must be declared somewhere in your application as public static final fields, and the corresponding SQL statements must appear somewhere in an .sql file.

(Please see these items in the example application for an illustration : web.xml, UserDAO, and csrf.sql.)

Post-processing

If a session is present, then this class will use a custom response wrapper to alter the response:

if the response has content-type of text/html (or null), then scan the response for all {@code
} tags with method='POST'.
for each such {@code } tag, add a hidden parameter in the following style :
```
<input type='hidden' name='web4j_key_for_form_source_id' value='151jdk65654dasdf545sadf6a5s4f'>
```

The name of the hidden parameter is taken from {@link #FORM_SOURCE_ID_KEY}, and the value of that hidden parameter is the random token created during the pre-processing stage.

ApplicationFirewall

This class cooperates closely with {@link hirondelle.web4j.security.ApplicationFirewallImpl}. It is the firewall which performs the actual test to make sure the POSTed form came from your web app.

Warning Regarding Error Pages

This Filter uses a wrapper for the response. When a Filter wraps the response, the error page customization defined by web.xml will likely not function. (This may be a defect of the Servlet API itself - see section 9.9.3.) That is, when an error occurs when using this Filter, the generic error pages defined by the container may be served, instead of the custom error pages you have configured in web.xml.

This filter will only affect the response if its content-type is text/html or null. It will not affect any other type of response.