recommended usage is:
call session_start() somewhere in your code but before outputting anything to the browser
session_start();
include the Zebra_Form
require 'path/to/Zebra_Form.php';
instantiate the class
protection against CSRF attack will be automatically enabled
but will be less secure if a session is not started (as it will
rely on cookies)
$form = new Zebra_Form('my_form');
| public csrf ( string $csrf_storage_method = 'auto', integer $csrf_token_lifetime, array $csrf_cookie_config = ['path' => '/', 'domain' => '', 'secure' => false, 'httponly' => true] ) : void | ||
| $csrf_storage_method | string | (Optional) Sets whether the CSRF token should be stored in a cookie, in
a session variable, or let the script to automatically decide and use
sessions if available or a cookie otherwise.
Possible values are "auto", "cookie", "session" or boolean FALSE.
If value is "auto", the script will decide automatically on what to use:
if a session is already started then the CSRF token will be stored in a
session variable, or, if a session is not started, the CSRF token will be
stored in a cookie with the parameters as specified by the
csrf_cookie_config argument (read below).
If value is "cookie" the CSRF token will be stored in a cookie with the
parameters as specified by the csrf_cookie_config argument (read
below).
If value is "session" the CSRF token will be stored in a session variable
and thus a session must be started before instantiating the library.
If value is boolean FALSE (not recommended), protection against CSRF
attack will be disabled.
The stored value will be compared, upon for submission, with the value
stored in the associated hidden field, and if the two values do not match
the form will not validate.
Default is "auto".
@param integer $csrf_token_lifetime (Optional) The number of seconds after which the CSRF token is to be
considered as expired.
If set to "0" the tokens will expire at the end of the session (when the
browser closes or session expires).
Note that if csrf_storage_method is set to "session" this value cannot
be higher than the session's life time as, if idle, the session will time
out regardless of this value!
Default is 0.
@param array $csrf_cookie_config (Optional) An associative array containing the properties to be used when
setting the cookie with the CSRF token (if csrf_storage_method is
set to "cookie").
The properties that can be set are "path", "domain", "secure" and "httponly".
where:
- path - the path on the server in which the cookie will
be available on. If set to "/", the cookie will
be available within the entire domain. If set to
'/foo/', the cookie will only be available within
the /foo/ directory and all subdirectories such
as /foo/bar/ of domain. Default is "/" - domain - The domain that the cookie will be available on. To make the cookie available on all subdomains of example.com, domain should be set to to ".example.com". The . (dot) is not required but makes it compatible with more browsers. Setting it to "www.example.com" will make the cookie available only in the www subdomain. - secure - Indicates whether cookie information should only be transmitted over a HTTPS connection. Default is FALSE. - httponly - When set to TRUE the cookie will be made accessible only through the HTTP protocol. This means that the cookie won't be accessible by scripting languages, such as JavaScript. It has been suggested that this setting can effectively help to reduce identity theft through XSS attacks (although it is not supported by all browsers), but that claim is often disputed. Available only in PHP 5.2.0+ Default is FALSE Available only for PHP 5.2.0+ and will be ignored if not available. Not all properties must be set - for the properties that are not set, the default values will be used instead. @since 2.8.4 @return void |
| $csrf_token_lifetime | integer | |
| $csrf_cookie_config | array | |
| return | void | |
function csrf($csrf_storage_method = 'auto', $csrf_token_lifetime = 0, $csrf_cookie_config = array('path' => '/', 'domain' => '', 'secure' => false, 'httponly' => true))
{
// continue only if protection against CSRF attacks is not disabled and a token was not already generated
if ($csrf_storage_method !== false && (func_num_args() > 0 || $this->form_properties['csrf_token'] == '')) {
// set the storage method for the CSRF token
$this->form_properties['csrf_storage_method'] = strtolower(trim($csrf_storage_method));
// if the script should decide what method to use and a session is already started
if ($this->form_properties['csrf_storage_method'] == 'auto') {
// use sessions as storage method
if (isset($_SESSION)) {
$this->form_properties['csrf_storage_method'] = 'session';
} else {
$this->form_properties['csrf_storage_method'] = 'cookie';
}
}
// set the life time of the CSRF token
$this->form_properties['csrf_token_lifetime'] = $csrf_token_lifetime <= 0 ? 0 : $csrf_token_lifetime;
// set the configuration options for cookies
$this->form_properties['csrf_cookie_config'] = array_merge($this->form_properties['csrf_cookie_config'], $csrf_cookie_config);
// generate a new CSRF token (if it is the case)
// (if this method is called with any arguments it means it is called by the user and therefore the
// token should be regenerated)
$this->_csrf_generate_token(func_num_args() > 0 ? true : false);
// if protection against CSRF attacks is disabled, save the option for later use
} else {
$this->form_properties['csrf_storage_method'] = false;
}
}