Merge branch 'feature/user-guide-cleanup' into develop

1 files changed, 72 insertions, 41 deletions

diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst
index be1f8d205..fb875a0d9 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
+
+  <div class="custom-index container"></div>
+
 XSS Filtering
 =============
 
@@ -23,12 +30,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 +40,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 +54,21 @@ 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
+: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(
@@ -114,15 +97,63 @@ 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	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:	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);
+
+	.. method:: get_csrf_token_name()
+
+		:returns:	CSRF token name
+		:rtype:	string
+
+		Returns the CSRF token name (the ``$config['csrf_token_name']`` value).
+
+	.. 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.
+
+	.. 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
+		:returns:	Entity-decoded string
+		:rtype:	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