Difference between revisions of "CSRFGuard 2.2 Configuration Manual"

Latest revision as of 06:09, 28 September 2010

UNDER CONSTRUCTION

Overview

OWASP CSRFGuard 2.2 offers several advantages over previous releases. With these advantages comes a number of new and or updated configuration options. The purpose of this article is to document all of the configuration options supported by CSRFGuard 2.2 as well as any relevant use cases. All of this properties are configured in the "CSRFGuard.properties" file included in the "/conf" folder of the 2.2 distribution.

Response Handler

The 'org.owasp.csrfguard.handler.*' property determines what 'ResponseHandler' should be invoked to insert the unique request token in the HTML response. Defining what response handler to use takes the following format:

Format: org.owasp.csrfguard.handler.[SOME IDENTIFIER]=[CLASS NAME]
Example: org.owasp.csrfguard.handler.HTMLParserHandler=org.owasp.csrfguard.handlers.HTMLParserHandler

As we shall see in later examples, the [SOME IDENTIFIER] is used as an identifier when passing initialization parameters to a response handler. All of the response handlers implement the org.owasp.csrfguard.handlers.ResponseHandler interface and they attempt to insert the unique request token in all links, iframes, and forms. CSRFGuard 2.2 ships with four possible response handlers: HTMLParserHandler, RegExHandler, JavaScriptHandler, and DefaultHandler. Each of these handlers and their associated parameters are listed below.

org.owasp.csrfguard.handlers.HTMLParserHandler

This ResponseHandler utilizes the open-source htmlparser (http://htmlparser.sourceforge.net) to manipulate the HTML response. The HTMLParserHandler is very accurate, relatively fast, easy to use/develop with, and offers a solid foundation for future enhancements. For example, future versions of CSRFGuard may parse custom JavaScript and insert the token in various (ex. window.location) locations. Such robust enhancements to CSRFGuard cannot be achieved in a clean and easy-to-maintain manner in the other response handlers. However, the htmlparser has interesting side effects with HTML that is not well formed. The htmlparser will sometimes modify HTML that is not well-formed in an attempt to make it well-formed. As such, some of the HTML resulting from the handler may break functionality. One such example is the 'HttpOnly' lesson in WebGoat (written by some guy name Eric Sheridan). The HTML generated by this lesson is not well-formed (nested HTML forms) and the modifications made by the HTMLParserHandler actually break the functionality of the lesson. Specifically, the 'Yes No' radio buttons to not transmit all of the appropriate parameters.

The following sample configures CSRFGuard to use the HTMLParserHandler with no parameters. The HTMLParserHandler object does not accept any parameters.

# HTMLParserHandler - insert token through server-side HTML parser
org.owasp.csrfguard.handler.HTMLParserHandler=org.owasp.csrfguard.handlers.HTMLParserHandler

org.owasp.csrfguard.handlers.RegExHandler

This ResponseHandler attempts to parse the HTML response using regular expressions. Any text matching the regular expression will be replaced with text containing the unique request token. The RegExHandler is the exact same implementation used in OWASP CSRFGuard 1.0. While this implementation is faster than the HTMLParserHandler, it is less accurate. The code is overly complex and not as thoroughly tested as the other response handlers. This handler is considered deprecated and is no longer maintained.

The following sample configures CSRFGuard to use the RegExParserHandler. This handler accepts one parameter called "FormPattern" - this parameter is required. This regular expression is used to locate HTML forms in the HTML so the hidden field token can be inserted.

# RegExHandler - insert token through server-side regular expression
org.owasp.csrfguard.handler.RegExHandler=org.owasp.csrfguard.handlers.RegExHandler
org.owasp.csrfguard.handler.RegExHandler.FormPattern=(?i)</form>

org.owasp.csrfguard.handlers.JavaScriptHandler

This ResponseHandler searches the HTML response for a customizable HTML tag pattern and prepends custom JavaScript that will insert the unique request token when processed by the clients browser. The JavaScriptHandler is extremely accurate and very fast as it off-loads the work to the client. The JavaScriptHandler does not suffer from the problems the HTMLParserHandler suffers in terms of broken HTML. The custom JavaScript will be executed after the HTML is successfully parsed, decreasing the likelihood of conflicting with broken HTML. Furthermore, all of the work that was previously performed on the server by the two other handlers is now performed on the client. For most environments and applications, the JavaScriptHandler is the preferred response handler.

This handler accepts two parameters called "SearchPattern" and "ReplaceText". Both are required. The "SearchPattern" argument is a regular expression that is used to locate an HTML tag that is replaced with the appropriate CSRFGuard JavaScript. The "ReplaceText" parameter tells CSRFGuard what to replace the "SearchPattern" with. Within the "ReplaceText" string is a keyword called "${update}". This value is replaced with the appropriate JavaScript code that will dynamically insert the CSRF token. To help digest this, consider the following code snippet from the response handler:

private String updateHTML(String content, String tokenName, String token) throws IOException {
	String update = getFileContent(JAVASCRIPT_FILE);

	update = update.replace(NAME_STR, tokenName);
	update = update.replace(VALUE_STR, token);
	
	String s = getHandlerParameter(SEARCH_PATTERN);
	Pattern searchPattern = Pattern.compile(s);
	
	s = getHandlerParameter(REPLACE_TEXT);
	String replaceText = s.replace(UPDATE_PLACEHOLDER, update);
	
	return searchPattern.matcher(content).replaceAll(replaceText);
}

This particular piece of code first retrieves a resource JavaScript file from the Jar. Next, it adds in the OWASP CSRFGuard token name and value in place of some hard-coded place holder values. Next, the "SearchPattern" regular expression is compiled and the "ReplaceText" is retrieved and the "${update}" is replaced with the JavaScript file content. At this point, we replace all the HTML response text that matches the "SearchPattern" with the updated content found in the "replaceText" String.

The following sample configures CSRFGuard to use the JavaScriptHandler. It searches for a </body> tag and replaces it with the JavaScript update and a closing body tag.

# JavaScriptHandler - insert token through client-side JavaScript
org.owasp.csrfguard.handler.JavaScriptHandler=org.owasp.csrfguard.handlers.JavaScriptHandler
org.owasp.csrfguard.handler.JavaScriptHandler.SearchPattern=(?i)</body>
org.owasp.csrfguard.handler.JavaScriptHandler.ReplaceText=${update}\n</body>

org.owasp.csrfguard.handlers.DefaultHandler

The DefaultHandler is the "null terminator" of handlers. It does absolutely nothing. If you plan on using the CSRFGuard tag library, then you should specify the "DefaultHandler" as your response handler. For more information regarding the use of the tag library, see CSRFGuard_2.2_Tag_Usage.

The following sample configures CSRFGuard to use the DefaultHandler.

# Empty Handler - a handler that does nothing. Used in conjunction with the tag library
org.owasp.csrfguard.handler.DefaultHandler=org.owasp.csrfguard.handlers.DefaultHandler

Note: It is vitally important to thoroughly test the ResponseHandler in your environment before deploying it to production. There is risk that the modification of your HTML might break existing functionality.

Token Name

The "org.owasp.csrfguard.TokenName" directive determines the name of the token placed in the HTML response. The following sample sets the token name to OWASP_CSRFTOKEN:

# Unique Token Name
#
# Define the name of the CSRF token parameter. If commented out, the name of
# the parameter will be a random value.
org.owasp.csrfguard.TokenName=OWASP_CSRFTOKEN

Token Length

The "org.owasp.csrfguard.TokenLength" directive determines the length of the unique request token. The following sample sets the token length to 32 characters:

# Token Length
#
# Define how long the token should be.
org.owasp.csrfguard.TokenLength=32

PRNG

The "org.owasp.csrfguard.PRNG" property is used to specify what random number generator should be used to generate the random token. The following sample sets the PRNG to SHA1PRNG:

# Pseudo-random Number Generator
#
# Define what PRNG should be used to generate the token
org.owasp.csrfguard.PRNG=SHA1PRNG

New Token Redirect Page

Previous releases of OWASP CSRFGuard had a very innocuous bug that allowed for a one-time CSRF attack against a particular session. In previous versions, when the first request came in for a session, the token was created and the request (valid or forged!) would be allowed through. As a result, there existed the possibility of performing a CSRF attack against an unauthenticated and session-less user. To counter this particular deficiency, developers can specify a "landing page" for the initial request when the CSRF token is being created. Rather than allowing the initial request through after token creation, the user can be optionally redirected to a safe landing page. This is done by defining the "org.owasp.csrfguard.NewTokenRedirectPage" directive. The following example redirects the user to /TestApp/index.jsp when a new token is generated and placed in a new session:

# New Token Redirect Page
#
# Defines where to send a user if the token is being generated for the first time.
# Failure to define a redirect page will allow CSRF attacks to work for unauthenticated
# users
org.owasp.csrfguard.NewTokenRedirectPage=/TestApp/index.jsp

Parameterless Token Validation

Previous versions of CSRFGuard would validate every single request sent to a protected resource. Consider the case when you click the "Refresh" button or when you click a book mark. When these actions occur, no valid token will exist in the GET request. As a result, CSRFGuard will incorrectly detect an attack. To counter this issue, developers can configure OWASP CSRFGuard to only validate the request if there are one or more parameters in the request. This is achieved through the use of the "org.owasp.csrfguard.ParameterlessValidation" directive. If set to false, CSRFGuard will only validate if there is one or more parameters. If set to true, CSRFGuard will mark a parameterless request for a protected resource as a possible attack. Please understand the potential consequences of this configuration. There are many web applications (Ex. Drupal, http://www.drupal.org) that invoke server-side actions using parameterless requests. If your application has this behavior, then I would highly recommend you consider validating all requests by setting "ParameterlessValidation" to true. If your web application(s) does not invoke server-side actions using parameterless requests, consider setting "ParameterlessValidation" to false to increase overall user experience. The following configuration tells CSRFGuard to only validate the token if there exists one or more parameters in the request:

# Parameterless Token Validation
#
# Define whether or not the token validation should occur
# on pages that do not have HTTP parameters (except for the token itself).
#
# If false, only validate when there is at least one parameter
# If true, validate regardless of the number of parameters
#
# Ex: /TestApp/index.jsp has no parameters. No need to validate. Clicking refresh will cause issues.
# Ex: /AddCart/32 has no parameters. Visiting the URL will add item '32' to cart. We must validate token
org.owasp.csrfguard.ParameterlessValidation=false