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