CSRF

Cross-Site Request Forgery (CSRF) is a security vulnerability that allows attackers to perform actions on behalf of authenticated users without their consent. Centum’s CSRF protection helps prevent these attacks by generating, storing, and validating secure tokens for HTML forms.

How It Works

• A random token is generated and stored in the user’s session.
• The token is injected into forms as a hidden field.
• On form submission, the token is validated against the stored value.
• If the token matches, the request is considered genuine.

Overview

The Centum\Http\Csrf namespace provides three main classes:

• Generator: Generates random CSRF tokens.
• Storage: Stores and retrieves tokens using the session.
• Validator: Validates tokens on incoming requests.

Centum\Http\Csrf\Generator implements Centum\Interfaces\Http\Csrf\GeneratorInterface.

Centum\Http\Csrf\Storage implements Centum\Interfaces\Http\Csrf\StorageInterface.

Centum\Http\Csrf\Validator implements Centum\Interfaces\Http\Csrf\ValidatorInterface.

Centum\Http\Csrf\Generator(
);

Centum\Http\Csrf\Storage(
    Centum\Interfaces\Http\SessionInterface $session,
    Centum\Interfaces\Http\Csrf\GeneratorInterface $generator
);

Centum\Http\Csrf\Validator(
    Centum\Interfaces\Http\RequestInterface $request,
    Centum\Interfaces\Http\Csrf\StorageInterface $storage
);

Usage

1. Obtaining a CSRF Token

Wherever a POST request requires CSRF protection, the current token value can be obtained from a Storage object and injected into the view:

use Centum\Http\Csrf\Storage;
use Centum\Interfaces\Http\Csrf\GeneratorInterface;
use Centum\Interfaces\Http\SessionInterface;

/** @var SessionInterface $session */
/** @var GeneratorInterface $generator */

$csrfStorage = new Storage($session, $generator);

$csrfValue = $csrfStorage->get();

2. Add the Token to Your Form

<form>
    <input type="hidden" name="csrf" value="<?php echo $csrfValue; ?>">

    <!-- rest of the form -->
</form>

If you’re using Twig, you can use the Centum CSRF Twig extension by simply calling the csrf() function somewhere in the form:

<form>
    {{ csrf() }}

    <!-- rest of the form -->
</form>

The CSRF Twig extension also provides the csrfValue() function that returns the raw CSRF value which is useful when dealing with AJAX form submissions:

$.post(
    {
        url: "/update-password",
        data: {
            "newPassword":        $("#newPassword").val(),
            "newPasswordConfirm": $("#newPasswordConfirm").val(),
            "csrf":               "{{ csrfValue() }}"
        }
    }
);

3. Validate the Token

Call ValidatorInterface::validate() at the start of your form handler:

namespace App\Web\Forms;

use Centum\Interfaces\Http\Csrf\ValidatorInterface;
use Centum\Interfaces\Http\FormInterface;

class SubmissionForm implements FormInterface
{
    public function __construct(ValidatorInterface $csrfValidator)
    {
        $csrfValidator->validate();

        // ...
    }
}

4. Generate or Reset Tokens

Generate a new token:

use Centum\Interfaces\Http\Csrf\GeneratorInterface;

/** @var GeneratorInterface $csrfGenerator */

$newValue = $csrfGenerator->generate();

Values can be removed from the Session with the StorageInterface::reset() method:

use Centum\Interfaces\Http\Csrf\StorageInterface;

/** @var StorageInterface $csrfStorage */

$csrfStorage->reset();