hirondelle.web4j.security
Class CsrfFilter

Object
  hirondelle.web4j.security.CsrfFilter

All Implemented Interfaces:

Filter

public class CsrfFilter
extends Object
implements Filter

Protect your application from a 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.

Pre-processing

When a new user login is detected, this class will do the following :

• calculate a random form-source id, and place it in session scope, under the key FORM_SOURCE_ID_KEY. This value is difficult to guess.
• if there is any 'old' form-source id, place it in session scope as well, under the key 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 FORM_SOURCE_DAO_KEY.

This classes interacts with your database, and is configured using two items : FormSourceIdRead and FormSourceIdWrite. These two items are SqlId references. They tell this class which SQL statements to use when reading and writing form-source ids to the database. As usual, these 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 the response has content-type of text/html (or null), then scan the response for all <FORM> tags with method='POST'.
• for each such <FORM> tag, add a hidden parameter in the following style :

  <input type='hidden' name='web4j_key_for_form_source_id' value='151jdk65654dasdf545sadf6a5s4f'>

The name is taken from FORM_SOURCE_ID_KEY, and the value is the random token created during the pre-processing stage.

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.

Field Summary

static String	FORM_SOURCE_DAO_KEY Key for item stored in session scope.
static String	FORM_SOURCE_ID_KEY Key for item stored in session scope, and also name of hidden request parameter added to POSTed forms.
static String	PREVIOUS_FORM_SOURCE_ID_KEY Key for item stored in session scope.

Constructor Summary

CsrfFilter()

Method Summary

void	destroy() This implementation does nothing.
void	doFilter(ServletRequest aRequest, ServletResponse aResponse, FilterChain aChain) Protect against CSRF attacks.
void	init(FilterConfig aFilterConfig) Read in filter configuration.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORM_SOURCE_ID_KEY

public static final String FORM_SOURCE_ID_KEY

Key for item stored in session scope, and also name of hidden request parameter added to POSTed forms.

Value - "web4j_key_for_form_source_id".

The value of this item is generated randomly for each new user login, and contains a simple token that is hard to guess. Each POSTed form will be required by ApplicationFirewallImpl to include a hidden parameter of this name, and the value of such hidden parameters are matched to the corresponding item stored in session scope under the same key. These checks verify that POSTed forms have come from a trusted source.

See Also:

Constant Field Values

PREVIOUS_FORM_SOURCE_ID_KEY

public static final String PREVIOUS_FORM_SOURCE_ID_KEY

Key for item stored in session scope.

Value - "web4j_key_for_previous_form_source_id".

The value of this item is retrieved from the database for each new user login, and represents the form-source id for the user's immediately preceding session. When a match of form-source id against FORM_SOURCE_ID_KEY fails, then a second match is attempted against this item.

Please see the package description for an explanation of why this is necessary.

See Also:

Constant Field Values

FORM_SOURCE_DAO_KEY

public static final String FORM_SOURCE_DAO_KEY

Key for item stored in session scope.

Value - "web4j_key_for_form_source_dao".

This item points to an HttpSessionBindingListener object placed in each new session. When the session ends, that object will be unbound from the session, and will save the user's current form-source id to the database, for future use.

See Also:

Constant Field Values

Constructor Detail

CsrfFilter

public CsrfFilter()

Method Detail

init

public void init(FilterConfig aFilterConfig)

Read in filter configuration.

Reads in SqlId references used to read and write the user's form-source id.

See class comment and package-level description for further information.

Specified by:

init in interface Filter

destroy

public void destroy()

This implementation does nothing.

Specified by:

destroy in interface Filter

doFilter

public void doFilter(ServletRequest aRequest,
                     ServletResponse aResponse,
                     FilterChain aChain)
              throws IOException,
                     ServletException

Protect against CSRF attacks.

See class comment and package-level description for further information.

Specified by:

doFilter in interface Filter

Throws:

IOException

ServletException