From 5363f4647b4fba3a0f7a52230cc33889096651ca Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 12:31:53 +0200 Subject: [ci skip] Update the Security class docs --- user_guide_src/source/libraries/security.rst | 103 ++++++++++++++++----------- 1 file changed, 60 insertions(+), 43 deletions(-) (limited to 'user_guide_src/source/libraries/security.rst') diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 05553142f..3d0697bbe 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -23,12 +23,7 @@ Note: This function should only be used to deal with data upon submission. It's not something that should be used for general runtime processing since it requires a fair amount of processing overhead. -To filter data through the XSS filter use this function: - -$this->security->xss_clean() -============================ - -Here is an usage example:: +To filter data through the XSS filter use the ``xss_clean()`` method:: $data = $this->security->xss_clean($data); @@ -38,10 +33,10 @@ application/config/config.php file and setting this:: $config['global_xss_filtering'] = TRUE; -Note: If you use the form validation class, it gives you the option of -XSS filtering as well. +.. note:: If you use the form validation class, it gives you the option of + XSS filtering as well. -An optional second parameter, is_image, allows this function to be used +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 @@ -52,40 +47,20 @@ browser may attempt to execute. if ($this->security->xss_clean($file, TRUE) === FALSE) { - // file failed the XSS test + // file failed the XSS test } -$this->security->sanitize_filename() -==================================== - -When accepting filenames from user input, it is best to sanitize them to -prevent directory traversal and other security related issues. To do so, -use the sanitize_filename() method of the Security class. Here is an -example:: - - $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); - Cross-site request forgery (CSRF) ================================= -You can enable CSRF protection by opening your -application/config/config.php file and setting this:: +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 -``form_open()`` will automatically insert a hidden csrf field in -your forms. If not, then you can use ``csrf_get_token_name()`` -and ``csrf_get_hash()`` - +:func:`form_open()` will automatically insert a hidden csrf field in +your forms. If not, then you can use ``csrf_get_token_name()`` and ``csrf_get_hash()`` :: $csrf = array( @@ -114,15 +89,57 @@ by editing the 'csrf_exclude_uris' config parameter:: $config['csrf_exclude_uris'] = array('api/person/add'); -$this->security->get_csrf_token_name() -====================================== +*************** +Class Reference +*************** + +.. class:: CI_Security + + .. method:: xss_clean($str[, $is_image = FALSE]) + + :param string $str: Input string + :returns: 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. + + .. 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: 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); + + .. method:: get_csrf_token_name() + + :returns: string + + Returns the CSRF token name (the ``$config['csrf_token_name']`` value). + + .. method:: get_csrf_hash() + + :returns: string + + Returns the CSRF hash value. Useful in combination with ``get_csrf_token_name()`` + for manually building forms or sending valid AJAX POST requests. + + .. method:: entity_decode($str[, $charset = NULL]) -Returns the CSRF token name, which is set by -``$config['csrf_token_name']``. + :param string $str: Input string + :param string $charset: Character set of the input string -$this->security->get_csrf_hash() -================================ + 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. -Returns the CSRF hash value. Useful in combination with -``get_csrf_token_name()`` for manually building forms or -sending valid AJAX POST requests. \ No newline at end of file + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From cc042095bcce9856402cc04997f44310074716e0 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:08:27 +0200 Subject: [ci skip] Some more generic user guide cleanup --- user_guide_src/source/libraries/security.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'user_guide_src/source/libraries/security.rst') diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 3d0697bbe..8d7ccb1ab 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -5,6 +5,13 @@ Security Class The Security Class contains methods that help you create a secure application, processing input data for security. +.. contents:: + :local: + +.. raw:: html + +
+ XSS Filtering ============= -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/security.rst | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) (limited to 'user_guide_src/source/libraries/security.rst') diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 451fadf93..fb875a0d9 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -105,17 +105,19 @@ Class Reference .. method:: xss_clean($str[, $is_image = FALSE]) - :param string $str: Input string - :returns: mixed + :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. .. 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: string + :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. @@ -131,23 +133,27 @@ Class Reference .. method:: get_csrf_token_name() - :returns: string + :returns: CSRF token name + :rtype: string Returns the CSRF token name (the ``$config['csrf_token_name']`` value). .. method:: get_csrf_hash() - :returns: string + :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. .. method:: entity_decode($str[, $charset = NULL]) - :param string $str: Input string - :param string $charset: Character set of the input string + :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. + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. \ No newline at end of file -- cgit v1.2.3-24-g4f1b