Security Class

The security class allows you to have CSRF protection in your application.

Configuration

The security class is configured through the security section of the app/config/config.php configuration file.

The following security configuration settings can be defined:

Param Type Default Description
token_salt string 
'put your salt value here...'
 Salt used to generate secure tokens. Make sure this contains something random to make sure your tokens are not predictable.
csrf_token_key string 
'fuel_csrf_token'
 Name used for the CSRF token cookie, and the name of the form field containing the token.
csrf_expiration integer 
0
 Expiration time for the CRSF token cookie. Default, the cookie expires at end of browser session.
csrf_bad_request_on_fail boolean 
false
 If true, a HttpBadRequestException will be thrown when csrf token validation fails. If false, a generic SecurityException will be thrown. Defaults to false for B/C reasons.
uri_filter array 
array('htmlentities')
 Array of callable items (PHP functions, object methods, static class methods) used to filter the URI. By default, it uses PHP's htmlentities internal function.
input_filter array 
array()
 Array of callable items (PHP functions, object methods, static class methods) used to filter $_GET, $_POST and $_COOKIE. By default, no input filters are defined.
output_filter array 
array('Security::htmlentities')
 Array of callable items (PHP functions, object methods, static class methods) used to filter variables send to a View or Presenter. For security reasons, you are required to define an output filter.
htmlentities_flags integer 
null
 Flags to be used when encoding HTML entities. Defaults to ENT_QUOTES if nothing is defined.
htmlentities_double_encode boolean 
null
 Whether of not already encoded entities should be encoded again. Defaults to false if nothing is defined.
auto_filter_output boolean 
true
 When true, all variables passed on to view objects are automatically encoded.
whitelisted_classes array 
array('stdClass', 'Fuel\\Core\\View',
 'Fuel\\Core\\Presenter', 'Closure')
 When auto encoding of view variables is enabled, you can run into issues when passing objects to the view. Classes defined in this array will be exempt from auto encoding.
csrf_autoload boolean 
false
 When true, load and check the CSRF token using check_token() automatically. A SecurityException will be thrown if the check fails.
csrf_autoload_methods array 
array('post', 'put', 'delete')
 When csrf_autoload is true, the CSRF token will be validated for all http methods in this array.
csrf_auto_token boolean 
false
 When true, Form::open() adds CSRF token hidden field automatically.

Note that if you enable "csrf_autoload", ALL your HTTP requests of the specified type MUST contain a CSRF token, or the validation will fail and a SecurityException will be thrown.

If you want to deal with CSRF validation failures when autoload is enabled, you can catch the SecurityException in your index.php.

check_token($value = null)

The check_token method allows you to check the CSRF token.
Check token also ensures a token is present and will reset the token for the next session when it receives a value to check (no matter the result of the check).

Static Yes
Parameters
Param Default Description
$value 
null
 CSRF token to be checked, checks value from POST or JSON input when not given.
Returns boolean
Example 
Security::check_token();

fetch_token()

The fetch_token method allows you to fetch the CSRF token from the cookie.

Static Yes
Parameters None
Returns string
Example 
$csrf_token = Security::fetch_token();

set_token($rotate = true)

The set_token method allows you to set the next CSRF token to be used, or to force a token rotation.

Static Yes
Parameters
Param Default Description
$rotate 
true
 If true, generation of a new CSRF token is forced. If false, an existing CSRF token is reused if available.
Example 
Security::set_token();

generate_token()

The generate_token method allows you to generate a secury token. This method is used to generate CSRF tokens, but can be used anywhere in your application where you need a secure random token.

Static Yes
Parameters None
Returns string
Example 
$token = Security::generate_token();

clean($value, $filters = null)

The clean method allows you clean data using the filters provided.

Static Yes
Parameters
Param Default Description
$value Required The value to be cleaned. This can be a string value, or an array of string values.
$filters 
null
 The filters to be used to clean the string(s). A filter can be a single value, or an array of values. Each value must be a valid PHP callback. You may specify functions ('htmlentities'), objects ($this), or static methods ('Classname::method').
Returns string
Example 
// first strip tags, convert html entities in the remaining data, and finish it off using our special cleaning solution
$filters = array('strip_tags', 'htmlentities', '\\cleaners\\soap::clean');
$text = Security::clean($text, $filters);

strip_tags($value)

The strip_tags method allows you to strip HTML and PHP tags from a string.

Static Yes
Parameters
Param Default Description
$value Required The input string.
Returns string
Example 
$text = '<p>Test paragraph.</p>';
$text = Security::strip_tags($text);

xss_clean($value, array $options = array())

The xss_clean method allows you to strip dangerous HTML tags from a string, using the HTMLawed library.

Static Yes
Parameters
Param Default Description
$value Required The input string.
$options 
array()
 Optional configuration array for htmLawed, if you require custom cleaning rules.
Returns string
Example 
$text = '<SCRIPT>alert("XSS attack!")</SCRIPT>';
$text = Security::xss_clean($text);

htmlentities($value, $flags = null, $encoding = null, $double_encode = null)

The htmlentities method allows you to turn HTML characters into their entity equivalent. This method operates identical to PHP's htmlentities() function but supports arrays and objects as well.

Static Yes
Parameters
Param Default Description
$value Required The input value.
$flags 
null
 Flags to be passed to htmlentities(). If not given and not configured, it will default to ENT_QUOTES.
$encoding 
null
 The encoding used for the value passed. If not given it will default the FuelPHP's default encoding.
$double_encoding 
null
 If true, already encoded values will not be encoded again. If not given and not configured it will default to false.
Returns mixed
Throws RuntimeException, in case an object has been passed that can't be cast as string.
Example 
$text = '<p>Test paragraph.</p>';
$text = Security::htmlentities($text);

js_fetch_token()

The js_fetch_token method allows you to produce JavaScript fuel_csrf_token() function that will return the current CSRF token when called. Use to fill right field on form submit for AJAX operations.

Static Yes
Parameters None
Returns string
Example 
// output the javascript function
echo Security::js_fetch_token();

// you can now use the generated function in the javascript code on your page
<script type="text/javascript">
	var current_token = fuel_csrf_token();
</script>

js_set_token()

The js_set_token method allows you to produce JavaScript fuel_set_csrf_token() function that will set the current CSRF token field in the form when called. Use this on an onsubmit of a form, to update the hidden token field in the form with the current value of the csrf cookie. You have to use this when you want to allow multiple windows open, and use a strict rotation and expiry of the CSRF token.

Static Yes
Parameters None
Returns string
Example 
// output the javascript function
echo Security::js_set_token();

// you use the function generated as an onsubmit function, like so.
// do NOT forget the 'this' parameter, so the function knows which form to update!
<form onsubmit="fuel_set_csrf_token(this);">
	<!-- do your stuff here -->
</form>

Procedural helpers

e($string)

The e function is an alias for Security::htmlentities.

Parameters
Param Default Description
$string required The input value.
Returns string, result from Security::htmlentities
Example 
$text = '<p>Test paragraph.</p>';
$text = e($text);