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. All of this properties are configured in the "CSRFGuard.properties" file included in the "/conf" folder of the 2.2 distribution.
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.
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
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
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