br/, (*1)
br/, (*2)
[](https://github.com/linna/csrf-guard/actions)
[](https://sonarcloud.io/summary/new_code?id=linna_csrf-guard)
[](https://github.com/php-pds/skeleton)
[](http://php.net)
About
Provide a class for generate and validate tokens utilized against Cross-site Request Forgery., (*3)
Note: Don't consider this class a definitive method to protect your web site/application. If you wish deepen
how to prevent csrf you can start here, (*4)
Requirements
This package require
* php 7.0 until version v1.1.2
* php 7.1 from v1.2.0
* php 7.4 from v1.4.0
* php 8.1 from v2.0.0, (*5)
Installation
With composer:, (*6)
composer require linna/csrf-guard
Token types
Note: Storage it's intended that the data about token or the token is stored in session., (*7)
The package provides three types of token:
- Encryption-based CSRF token
- HMAC-based CSRF token
- Synchronizer CSRF token, (*8)
Encryption-based token
Encryption-based CSRF token is a token that is the result of a cryptographic algorithm, some data is encrypted using a
secret key only known from the server .The implementation in this library uses libsodium aead contruction
XChaCha20-Poly1305. The token has expire time and require local storage., (*9)
The token security depends from:
- secret key storage
- strength of XChaCha20-Poly1305, (*10)
This token is valid until validated or until it expires. It's possible to select a length of the token. The length of
the token doesn't affect the storage used., (*11)
The key used for the engryption is generated for every session, the nonce for every token., (*12)
HMAC-based token
HMAC-based CSRF token is a token that is computed by applying an HMAC function to some data and a secret key that is
only known from the server. The implementation in this library uses php hash_hmac with the sha3-384 algorithm.
This type of token deosn't require local storage and it has an expire time., (*13)
The token security depends from:
- secret key storage
- strength of sha3-384, (*14)
This token is valid until expires and can be validate more times. Also has fixed length and it's not possible to change
it to obtain a shorter or longer token., (*15)
The key used to authenticate is fully managed by the user of the library., (*16)
Synchronizer token
The Synchronizer CSRF token is a token randomly generated. This library uses php random_bytes. The token has expire
time and require local storage., (*17)
The token security depends from:
- the length of the token, (*18)
This token is valid until validated or until it expires. It's possible to select a length of the token. The length of
the token affects the storage used., (*19)
Usage
Note: Session must be started before you create the instance of a provider,
if no a SessionNotStartedException will be throw, this is not true if you use the HmacTokenProvider., (*20)
Get started
How to get and validate a token using few lines of code., (*21)
Generate a provider
//start the session
\session_start();
//generate token provider
$provider = ProviderSimpleFactory::getProvider();
Get a token
//previous php code
//get a token from provider
$token = $provider->getToken();
Validate it
//previous php code
//true if valid, false otherwise
$isValid = $provider->validate($token);
Provider configuration
The ProviderSimpleFactory::getProvider() static method has two parameters:
- the provider
- options for the provider, (*22)
EncryptionTokenProvider config
| Options |
Default Value |
Unity |
Range |
Mandatory |
| expire |
600 |
seconds |
0-86400 |
no |
| storageSize |
10 |
tokens |
2-64 |
no |
| tokenLength |
16 |
bytes |
16-128 |
no |
Example of usage:, (*23)
//start the session
\session_start();
//get specific encryption token provider
$provider = ProviderSimpleFactory::getProvider(
provider: EncryptionTokenProvider::class, // specific token provider
options: [ // options
'expire' => 3600, // token expire in 3600 seconds, 1 hour
'storageSize' => 16, // provider can store maximum 1 key and 16 nonces per session,
'tokenLength' => 16 // desidered token length in bytes, token will be used as plaintext and not stored
]
);
HmacTokenProvider config
| Options |
Default Value |
Unity |
Range |
Mandatory |
| value |
// |
yes |
| key |
// |
yes |
| expire |
600 |
seconds |
0-86400 |
no |
Example of usage:, (*24)
//get specific hmac token provider
$provider = ProviderSimpleFactory::getProvider(
provider: HmacTokenProvider::class, // specific token provider
options: [ // options
'value' => 'value will be hashed in token', // value will be hashed in token
'key' => 'key_to_authenticate' // key to authenticate the hash
]
);
SynchronizerTokenProvider config
| Options |
Default Value |
Unity |
Range |
Mandatory |
| expire |
600 |
seconds |
0-86400 |
no |
| storageSize |
10 |
tokens |
2-64 |
no |
| tokenLength |
32 |
bytes |
16-128 |
no |
Example of usage:, (*25)
//start the session
\session_start();
//get specific syncronizer token provider
$provider = ProviderSimpleFactory::getProvider(
provider: SynchronizerTokenProvider::class, // specific token provider
options: [ // options
'expire' => 3600, // token expire in 3600 seconds, 1 hour
'storageSize' => 16, // provider can store maximum 16 token per session,
'tokenLength' => 32 // desidered token length in bytes, token will be the double in chars
]
);
Wallogit.com
