Security Class
**************

The Security Class contains methods that help you create a secure
application, processing input data for security.

* XSS Filtering

* Cross-site request forgery (CSRF)

* Class Reference


XSS Filtering
=============

CodeIgniter comes with a Cross Site Scripting prevention filter, which
looks for commonly used techniques to trigger JavaScript or other
types of code that attempt to hijack cookies or do other malicious
things. If anything disallowed is encountered it is rendered safe by
converting the data to character entities.

To filter data through the XSS filter use the "xss_clean()" method:

   $data = $this->security->xss_clean($data);

An optional second parameter, *is_image*, allows this function to be
used to test images for potential XSS attacks, useful for file upload
security. When this second parameter is set to TRUE, instead of
returning an altered string, the function returns TRUE if the image is
safe, and FALSE if it contained potentially malicious information that
a browser may attempt to execute.

   if ($this->security->xss_clean($file, TRUE) === FALSE)
   {
           // file failed the XSS test
   }

Important:

  If you want to filter HTML attribute values, use "html_escape()"
  instead!


Cross-site request forgery (CSRF)
=================================

You can enable CSRF protection by altering your
**application/config/config.php** file in the following way:

   $config['csrf_protection'] = TRUE;

If you use the form helper, then "form_open()" will automatically
insert a hidden csrf field in your forms. If not, then you can use
"get_csrf_token_name()" and "get_csrf_hash()"

   $csrf = array(
           'name' => $this->security->get_csrf_token_name(),
           'hash' => $this->security->get_csrf_hash()
   );

   ...

   <input type="hidden" name="<?=$csrf['name'];?>" value="<?=$csrf['hash'];?>" />

Tokens may be either regenerated on every submission (default) or kept
the same throughout the life of the CSRF cookie. The default
regeneration of tokens provides stricter security, but may result in
usability concerns as other tokens become invalid (back/forward
navigation, multiple tabs/windows, asynchronous actions, etc). You may
alter this behavior by editing the following config parameter

   $config['csrf_regenerate'] = TRUE;

Select URIs can be whitelisted from csrf protection (for example API
endpoints expecting externally POSTed content). You can add these URIs
by editing the ‘csrf_exclude_uris’ config parameter:

   $config['csrf_exclude_uris'] = array('api/person/add');

Regular expressions are also supported (case-insensitive):

   $config['csrf_exclude_uris'] = array(
           'api/record/[0-9]+',
           'api/title/[a-z]+'
   );


Class Reference
===============

class CI_Security

   xss_clean($str[, $is_image = FALSE])

      Parameters:
         * **$str** ("mixed") – Input string or an array of strings

      Returns:
         XSS-clean data

      Return type:
         "mixed"

      Tries to remove XSS exploits from the input data and returns the
      cleaned string. If the optional second parameter is set to true,
      it will return boolean TRUE if the image is safe to use and
      FALSE if malicious data was detected in it.

      Important:

        This method is not suitable for filtering HTML attribute
        values! Use "html_escape()" for that instead.

   sanitize_filename($str[, $relative_path = FALSE])

      Parameters:
         * **$str** ("string") – File name/path

         * **$relative_path** ("bool") – Whether to preserve any
           directories in the file path

      Returns:
         Sanitized file name/path

      Return type:
         "string"

      Tries to sanitize filenames in order to prevent directory
      traversal attempts and other security threats, which is
      particularly useful for files that were supplied via user input.

         $filename = $this->security->sanitize_filename($this->input->post('filename'));

      If it is acceptable for the user input to include relative
      paths, e.g. *file/in/some/approved/folder.txt*, you can set the
      second optional parameter, "$relative_path" to TRUE.

         $filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE);

   get_csrf_token_name()

      Returns:
         CSRF token name

      Return type:
         "string"

      Returns the CSRF token name (the "$config['csrf_token_name']"
      value).

   get_csrf_hash()

      Returns:
         CSRF hash

      Return type:
         "string"

      Returns the CSRF hash value. Useful in combination with
      "get_csrf_token_name()" for manually building forms or sending
      valid AJAX POST requests.

   entity_decode($str[, $charset = NULL])

      Parameters:
         * **$str** ("string") – Input string

         * **$charset** ("string") – Character set of the input string

      Returns:
         Entity-decoded string

      Return type:
         "string"

      This method acts a lot like PHP’s own native
      "html_entity_decode()" function in ENT_COMPAT mode, only it
      tries to detect HTML entities that don’t end in a semicolon
      because some browsers allow that.

      If the "$charset" parameter is left empty, then your configured
      "$config['charset']" value will be used.

   get_random_bytes($length)

      Parameters:
         * **$length** ("int") – Output length

      Returns:
         A binary stream of random bytes or FALSE on failure

      Return type:
         "string"

      A convenience method for getting proper random bytes via
      "mcrypt_create_iv()", "/dev/urandom" or
      "openssl_random_pseudo_bytes()" (in that order), if one of them
      is available.

      Used for generating CSRF and XSS tokens.

      Note:

        The output is NOT guaranteed to be cryptographically secure,
        just the best attempt at that.
