CSRFGuard 2.2 Configuration Manual
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.
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
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
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>
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.