summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/security.rst
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2019-01-16 16:49:35 +0100
committerAndrey Andreev <narf@devilix.net>2019-01-16 16:49:35 +0100
commitc576995304fc3609cca0b7b92d1b2cd611ec82f5 (patch)
treec8b9121cb295b56bbabe3aeaad0a3eb1f2d390bb /user_guide_src/source/libraries/security.rst
parent4eaf80a6ec0b58a0adc95638153363e00ebf5378 (diff)
[ci skip] 3.1.10 release
Diffstat (limited to 'user_guide_src/source/libraries/security.rst')
-rw-r--r--user_guide_src/source/libraries/security.rst172
1 files changed, 0 insertions, 172 deletions
diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst
deleted file mode 100644
index 868112684..000000000
--- a/user_guide_src/source/libraries/security.rst
+++ /dev/null
@@ -1,172 +0,0 @@
-##############
-Security Class
-##############
-
-The Security Class contains methods that help you create a secure
-application, processing input data for security.
-
-.. contents::
- :local:
-
-.. raw:: html
-
- <div class="custom-index container"></div>
-
-*************
-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
- :php:func:`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 :doc:`form helper <../helpers/form_helper>`, then
-:func:`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
-***************
-
-.. php:class:: CI_Security
-
- .. php:method:: xss_clean($str[, $is_image = FALSE])
-
- :param mixed $str: Input string or an array of strings
- :returns: XSS-clean data
- :rtype: 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 :php:func:`html_escape()` for that instead.
-
- .. php:method:: sanitize_filename($str[, $relative_path = FALSE])
-
- :param string $str: File name/path
- :param bool $relative_path: Whether to preserve any directories in the file path
- :returns: Sanitized file name/path
- :rtype: 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);
-
- .. php:method:: get_csrf_token_name()
-
- :returns: CSRF token name
- :rtype: string
-
- Returns the CSRF token name (the ``$config['csrf_token_name']`` value).
-
- .. php:method:: get_csrf_hash()
-
- :returns: CSRF hash
- :rtype: string
-
- Returns the CSRF hash value. Useful in combination with ``get_csrf_token_name()``
- for manually building forms or sending valid AJAX POST requests.
-
- .. php:method:: entity_decode($str[, $charset = NULL])
-
- :param string $str: Input string
- :param string $charset: Character set of the input string
- :returns: Entity-decoded string
- :rtype: 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.
-
- .. php:method:: get_random_bytes($length)
-
- :param int $length: Output length
- :returns: A binary stream of random bytes or FALSE on failure
- :rtype: 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.