Download the PHP package solventt/csrf-protection without Composer

Table of Contents

1. Features
2. Installing
3. Usage
4. A real use case
5. A custom token name
6. A custom failure handler
7. A custom token storage
8. A custom token generation algorithm
9. A custom CSRF token class
10. The CSRF token in custom request headers

This is a PSR-15 compatible middleware that implements protection against cross-site request forgery.

In this package, the CSRF protection is organized according to the Synchronizer Token pattern described on the OWASP website.

Features

This package uses token masking (randomizing by XORing with a random secret). This method is recommended for protection against BREACH attacks.

The CSRF token is generated and saved once per session (this can be changed). But thanks to the mask, the token will be unique each time it is requested.

Masking the token eliminates the problem of false CSRF triggering on the server when you click the "Back" button in the browser.

Installing

Usage

To get a name and valid value of the token do:

Somewhere in HTML:

When the getValue() method is called the first time, the CSRF token is generated and stored into a storage (usually in a user session). On subsequent method calls, a CSRF token value is taken from a storage.

By default, the getValue() method returns a masked token. If you need a raw value of the CSRF token that is stored in a session, specify false as the first argument:

If you want to generate the token of a certain length, specify it as the second argument in the getValue() method:

The default token length is 32 characters and cannot be less than 15.

Since the CSRF token is randomly masked, there is no need to regenerate it within the same session. But if such a need occurs, do:

A real use case

It is an example of using the CSRF protection in the Slim micro framework.

config/csrf.php:

routing/middleware.php:

config/twig.php:

views/template.twig:

A custom token name

The default token name is _csrf. But you can specify your own name by adding it as the third argument to the MaskedCsrfToken constructor:

A custom failure handler

By default, if the CSRF tokens do not match, the client receives code 400, and the 'Bad Request' message.

But you can define your own logic for handling CSRF fails. Just add an anonymous function as the third argument to the CsrfMiddleware constructor:

Notice: an anonymous function must return an instance that implements ResponseInterface.

A custom token storage

Out of the box, this package provides the SessionTokenStorage class that works directly with the superglobal $_SESSION. If that's not what you need, you can write your own version of the token storage. Then your class must implement TokenStorageInterface interface:

For example, your code uses an abstraction over $_SESSION to handle sessions. Then your token storage might look like this:

A custom token generation algorithm

You can define your own logic for generating the CSRF token and adding/removing the token mask. To do this, your class must implement SecurityInterface:

A custom CSRF token class

This package provides the MaskedCsrfToken class representing the CSRF token. But you can write your own implementation of the token according to the CsrfTokenInterface:

The CSRF token in custom request headers

If no CSRF token is found in request body, the middleware checks for the X-CSRF-Token header. You can provide your own header name using the setHeaderName method:

It is relevant, for example, for AJAX requests.