GDS Anti-CSRF Library

**Authors:** Erik Larsson ([email protected]), Ron Gutierrez ([email protected])
**Company:** Gotham Digital Science, LLC

This library is designed to be a secure and flexible solution for protecting J2EE web applications against Cross-Site Request Forgery (CSRF) exposures. The solution was initially derived from the anti-CSRF protection built into the SendSafely platform and the specific requirements of a leading financial institution looking to deploy a common, firm-wide solution to CSRF prevention. Open source alternatives were investigated, and while each had its pros and cons and could have potentially worked in a specific instance, none of them was flexible enough to adapt to the diverse and evolving web technology stack of our financial services partner. Since the initial design and implementation, development has continued and the library has undergone several enterprise integrations.

The following is a list of requirements and guidelines that governed the initial design and implementation of the GDS Anti-CSRF library. Although the implementation is specific to Java/J2EE web application architectures, these requirements and guidelines have been generalized to the extent possible. The intention is to provide developers of other common web technologies a foundation for developing an Anti-CSRF solution with equivalent security and integration flexibility.

1. CSRF Protection Must Support Stateless and Stateful Modes

The solution must work with web applications that do and do not utilize session storage.

2. CSRF Token Life Must Be Configurable

Token life options supported by Stateless and Stateful modes must be configurable.

3. CSRF Token Protection Scope Must Be Configurable

It must be possible to configure the following:

• White list of exempt URLs - By default, a non-expired token will be considered valid for all application requests (i.e. site-wide protection). It must be possible to exempt specific URLs from site-wide CSRF token validation.
• Black list of protected URLs – it must be possible to only protect specific URLs with a CSRF token

4. API and Integration Documentation Must Be Provided

The solution API and integration steps must be clearly documented.

5. CSRF Tokens Should be User Specific

The CSRF token should be tied to the authenticated user’s identity.

6. CSRF Token Protection Scope Should Support Form Specific Protection

The scope of protection can be configured so that a non-expired token is tied to a specific form.

Note: Currently, the library supports site wide and URL specific tokens. Form specific tokens is on the roadmap for a future version.

7. Simple Integration with Existing Web Application Technology Stack

The solution should adhere to the following principles to ensure it is as plug-n-play as possible:

• Designed as a library that can be referenced by existing applications
• Utilize core platform-level APIs and specifications
• Minimize use of 3rd party libraries
• Aim to limit code modifications to source code of the integrating application

Refer to the Wiki for complete documentation and setup instructions.

Copyright 2014-2016 Gotham Digital Science LLC

Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.