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. 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 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 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.

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 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 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 <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 of the hidden parameter is taken from 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 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.

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	addCsrfToken(HttpServletRequest aRequest) Add a CSRF token to an existing session that has no user login.
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

addCsrfToken

public void addCsrfToken(HttpServletRequest aRequest)
                  throws ServletException

Add a CSRF token to an existing session that has no user login.

This method is called only when a session created by an Action, instead of the usual login mechanism. See ActionImpl.createSessionAndCsrfToken() for important information.

Throws:

ServletException