Difference between revisions of "CSRFGuard 2.2 Configuration Manual"

Revision as of 22:17, 9 April 2008

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.

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, [FIXME click here].

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.