PHP-CSRF
Cross-Site Request Forgery protection PHP library
PHP-CSRF manage, generate and validate hashes, on the user's session, to provide a basic protection from Cross-Site Request Forgery.
Download
- Direct download php-csrf.php file (right click save as).
- Using wget
wget -O php-csrf.php https://raw.githubusercontent.com/GramThanos/php-csrf/master/php-csrf.php
Example usage
<?php
// Include the PHP-CSRF library
include('php-csrf.php');
// Start or Resume a session
session_start();
// Initialize an instance
$csrf = new CSRF();
// If form was submitted
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
// Validate that a correct token was given
if ($csrf->validate('my-form')) {
// Success
}
else {
// Failure
}
}
?>
<!-- Your normal HTML form -->
<form method="POST">
<!-- Print a hidden hash input -->
<?=$csrf->input('my-form');?>
...
<input type="submit" value="Submit"/>
</form>API
Create a csrf object
$csrf = new CSRF($session_name='csrf-lib', $input_name='key-awesome', $hashTime2Live=0, $hashSize=64);$session_namethe name to be used for the session variable.$input_namethe name to be used on the HTML input with the hash.$hashTime2Livethe default hash live time of each hash in seconds. Should be>=0. If zero, by default the hash will not expire.$hashSizethe default hash size in chars. Should be>0.
Clear excess hashes
$deleted = $csrf->clearHashes($context='', $max_hashes=0);$contextthe name of the group to clear$max_hashesthe number of hashes to keep. If the hash population is bigger, the oldest hashes will be deleted.- returns the number of deleted hashes.
Generate HTML input element code
echo $csrf->input($context='', $time2Live=-1, $max_hashes=5)$contextthe name of the group to save the hash to. Usually, it is different for each form.$time2Livethe hash live time in seconds. If zero, the hash will not expire. If negative, the default value will be used.$max_hashesthe hash limit of the group. If the group has already reached this limit, the oldest hash will be discarded.- returns a string with the HTML code. Example return value
'<input type="hidden" name="key-awesome" value="1234567890ABCDEF1234567890ABCDEF"/>'.
Generate javascript script element code (alternative)
echo $csrf->script($context='', $name='', $declaration='var', $time2Live=-1, $max_hashes=5)$contextthe name of the group to save the hash to. Usually, it is different for each form.$namethe name of the javascript variable. If it is empty string, the name of theinput_namewill be used, but the default one is an invalid variable name.$declarationthe declaration key word of the variable, usuallyvar,letorconst.$time2Livethe hash live time in seconds. If zero, the hash will not expire. If negative, the default value will be used.$max_hashesthe hash limit of the group. If the group has already reached this limit, the oldest hash will be discarded.- returns a string with the HTML script code. Example return value
'<script type="text/javascript">var name = "1234567890ABCDEF1234567890ABCDEF";</script>'.
Generate javascript variable code (alternative)
echo $csrf->javascript($context='', $name='', $declaration='var', $time2Live=-1, $max_hashes=5)$contextthe name of the group to save the hash to. Usually, it is different for each form.$namethe name of the javascript variable. If it is empty string, the name of theinput_namewill be used, but the default one is an invalid variable name.$declarationthe declaration key word of the variable, usuallyvar,letorconst.$time2Livethe hash live time in seconds. If zero, the hash will not expire. If negative, the default value will be used.$max_hashesthe hash limit of the group. If the group has already reached this limit, the oldest hash will be discarded.- returns a string with the javascript code. Example return value
'var name = "1234567890ABCDEF1234567890ABCDEF";'.
Generate hash as a string (alternative)
echo $csrf->string($context='', $time2Live=-1, $max_hashes=5)$contextthe name of the group to save the hash to. Usually, it is different for each form.$time2Livethe hash live time in seconds. If zero, the hash will not expire. If negative, the default value will be used.$max_hashesthe hash limit of the group. If the group has already reached this limit, the oldest hash will be discarded.- returns a string with the hash. Example return value
'1234567890ABCDEF1234567890ABCDEF'.
Check if a valid hash was posted
$is_valid = $csrf->validate($context='', $hash=null)$contextthe name of the group to search for the hash into.$hashthe hash to validate. Ifnull, the hash will be retrieved by the$_POSTor the$_GETobjects.- returns
trueif the validation was successful orfalseotherwise.
Get the hashes of a context
$is_valid = $csrf->getHashes($context='', $max_hashes=-1)$contextthe name of the group to get its hashes.$max_hashesmax number of hashes to get. If negative value, all the hashes will be returned.- returns an array of string hashes.
The hashes are saved on the $_SESSION under the a single variable using serialize and unserialize. Thus, if the session expires or get destroyed, the hashes would too.
About the Security
This library uses the openssl_random_pseudo_bytes function to generate random hashes. In order to be sure that your system can produce cryptographically strong hashes, you should run the following PHP code and check the result.
<?php
// Test if random_pseudo is cryptographically strong in your system
$hash = openssl_random_pseudo_bytes(32, $crypto_strong);
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>PHP-CSRF Test</title>
</head>
<body>
Is cryptographically strong: <?=($crypto_strong ? 'yes' : 'no');?><br>
</body>
</html>This library was created to provide a basic protection from Cross-Site Request Forgery attacks. Thus, sophisticated attacks like a timing attack may break the protection.
By using relative big hash sizes, relative short hash expiration times and small group hash limits, you can strengthen the security.
License
This project is under The MIT license. I do although appreciate attribute.
Copyright (c) 2020 Grammatopoulos Athanasios Vasileios
