Fr3nch13/CakePHP Utilities

CsrfProtectionMiddleware
in package
implements MiddlewareInterface

Provides CSRF protection & validation.

This middleware adds a CSRF token to a cookie. The cookie value is compared to token in request data, or the X-CSRF-Token header on each PATCH, POST, PUT, or DELETE request. This is known as "double submit cookie" technique.

If the request data is missing or does not match the cookie data, an InvalidCsrfTokenException will be raised.

This middleware integrates with the FormHelper automatically and when used together your forms will have CSRF tokens automatically added when $this->Form->create(...) is used in a view.

Tags
see
https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#double-submit-cookie

Table of Contents

Interfaces

MiddlewareInterface
Participant in processing a server request and response.

Constants

TOKEN_VALUE_LENGTH  = 16
TOKEN_WITH_CHECKSUM_LENGTH  = 56
Tokens have an hmac generated so we can ensure that tokens were generated by our application.

Properties

$_config  : array<string, mixed>
Config for the CSRF handling.
$skipCheckCallback  : callable|null
Callback for deciding whether to skip the token check for particular request.

Methods

__construct()  : mixed
Constructor
createToken()  : string
Create a new token to be used for CSRF protection
process()  : ResponseInterface
Checks and sets the CSRF token depending on the HTTP verb.
saltToken()  : string
Apply entropy to a CSRF token
skipCheckCallback()  : $this
Set callback for allowing to skip token check for particular request.
unsaltToken()  : string
Remove the salt from a CSRF token.
whitelistCallback()  : $this
Set callback for allowing to skip token check for particular request.
_addTokenCookie()  : ResponseInterface
Add a CSRF token to the response cookies.
_createCookie()  : CookieInterface
Create response cookie
_createToken()  : string
Create a new token to be used for CSRF protection
_unsetTokenField()  : ServerRequestInterface
Remove CSRF protection token from request data.
_validateToken()  : void
Validate the request data against the cookie token.
_verifyToken()  : bool
Verify that CSRF token was originally generated by the receiving application.
isHexadecimalToken()  : bool
Test if the token predates salted tokens.

Constants

TOKEN_WITH_CHECKSUM_LENGTH

Tokens have an hmac generated so we can ensure that tokens were generated by our application.

public int TOKEN_WITH_CHECKSUM_LENGTH = 56

Should be TOKEN_VALUE_LENGTH + strlen(hmac)

We are currently using sha1 for the hmac which creates 40 bytes.

Properties

$_config

Config for the CSRF handling.

protected array<string, mixed> $_config = ['cookieName' => 'csrfToken', 'expiry' => 0, 'secure' => false, 'httponly' => false, 'samesite' => null, 'field' => '_csrfToken']
  • cookieName The name of the cookie to send.
  • expiry A strotime compatible value of how long the CSRF token should last. Defaults to browser session.
  • secure Whether the cookie will be set with the Secure flag. Defaults to false.
  • httponly Whether the cookie will be set with the HttpOnly flag. Defaults to false.
  • samesite "SameSite" attribute for cookies. Defaults to null. Valid values: CookieInterface::SAMESITE_LAX, CookieInterface::SAMESITE_STRICT, CookieInterface::SAMESITE_NONE or null.
  • field The form field to check. Changing this will also require configuring FormHelper.

$skipCheckCallback

Callback for deciding whether to skip the token check for particular request.

protected callable|null $skipCheckCallback

CSRF protection token check will be skipped if the callback returns true.

Methods

__construct()

Constructor

public __construct([array<string, mixed> $config = [] ]) : mixed
Parameters
$config : array<string, mixed> = []

Config options. See $_config for valid keys.

createToken()

Create a new token to be used for CSRF protection

public createToken() : string
Return values
string

saltToken()

Apply entropy to a CSRF token

public saltToken(string $token) : string

To avoid BREACH apply a random salt value to a token When the token is compared to the session the token needs to be unsalted.

Parameters
$token : string

The token to salt.

Return values
string —

The salted token with the salt appended.

skipCheckCallback()

Set callback for allowing to skip token check for particular request.

public skipCheckCallback(callable $callback) : $this

The callback will receive request instance as argument and must return true if you want to skip token check for the current request.

Parameters
$callback : callable

A callable.

Return values
$this

unsaltToken()

Remove the salt from a CSRF token.

public unsaltToken(string $token) : string

If the token is not TOKEN_VALUE_LENGTH * 2 it is an old unsalted value that is supported for backwards compatibility.

Parameters
$token : string

The token that could be salty.

Return values
string —

An unsalted token.

whitelistCallback()

Set callback for allowing to skip token check for particular request.

public whitelistCallback(callable $callback) : $this

Use skipCheckCallback instead.

The callback will receive request instance as argument and must return true if you want to skip token check for the current request.

Parameters
$callback : callable

A callable.

Return values
$this

_createToken()

Create a new token to be used for CSRF protection

protected _createToken() : string

Use instead.

Return values
string

_verifyToken()

Verify that CSRF token was originally generated by the receiving application.

protected _verifyToken(string $token) : bool
Parameters
$token : string

The CSRF token.

Return values
bool

isHexadecimalToken()

Test if the token predates salted tokens.

protected isHexadecimalToken(string $token) : bool

These tokens are hexadecimal values and equal to the token with checksum length. While they are vulnerable to BREACH they should rotate over time and support will be dropped in 5.x.

Parameters
$token : string

The token to test.

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results