[ci skip] DocBlock improvements for Security library

1 files changed, 100 insertions, 77 deletions

diff --git a/system/core/Security.php b/system/core/Security.php
index d7c82712d..50d0ce052 100644
--- a/system/core/Security.php
+++ b/system/core/Security.php
@@ -37,45 +37,55 @@
 class CI_Security {
 
 	/**
-	 * Random Hash for protecting URLs
+	 * XSS Hash
 	 *
-	 * @var string
+	 * Random Hash for protecting URLs.
+	 *
+	 * @var	string
 	 */
 	protected $_xss_hash =	'';
 
 	/**
-	 * Random Hash for Cross Site Request Forgery Protection Cookie
+	 * CSRF Hash
+	 *
+	 * Random hash for Cross Site Request Forgery protection cookie
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	protected $_csrf_hash =	'';
 
 	/**
-	 * Expiration time for Cross Site Request Forgery Protection Cookie
-	 * Defaults to two hours (in seconds)
+	 * CSRF Expire time
+	 *
+	 * Expiration time for Cross Site Request Forgery protection cookie.
+	 * Defaults to two hours (in seconds).
 	 *
-	 * @var int
+	 * @var	int
 	 */
 	protected $_csrf_expire =	7200;
 
 	/**
-	 * Token name for Cross Site Request Forgery Protection Cookie
+	 * CSRF Token name
 	 *
-	 * @var string
+	 * Token name for Cross Site Request Forgery protection cookie.
+	 *
+	 * @var	string
 	 */
 	protected $_csrf_token_name =	'ci_csrf_token';
 
 	/**
-	 * Cookie name for Cross Site Request Forgery Protection Cookie
+	 * CSRF Cookie name
+	 *
+	 * Cookie name for Cross Site Request Forgery protection cookie.
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	protected $_csrf_cookie_name =	'ci_csrf_token';
 
 	/**
 	 * List of never allowed strings
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	protected $_never_allowed_str =	array(
 		'document.cookie'	=> '[removed]',
@@ -91,9 +101,9 @@ class CI_Security {
 	);
 
 	/**
-	 * List of never allowed regex replacement
+	 * List of never allowed regex replacements
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	protected $_never_allowed_regex = array(
 		'javascript\s*:',
@@ -104,7 +114,7 @@ class CI_Security {
 	);
 
 	/**
-	 * Initialize security class
+	 * Class constructor
 	 *
 	 * @return	void
 	 */
@@ -138,7 +148,7 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Verify Cross Site Request Forgery Protection
+	 * CSRF Verify
 	 *
 	 * @return	object
 	 */
@@ -188,10 +198,10 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set Cross Site Request Forgery Protection Cookie
+	 * CSRF Set Cookie
 	 *
-	 * @return	object
 	 * @codeCoverageIgnore
+	 * @return	object
 	 */
 	public function csrf_set_cookie()
 	{
@@ -234,9 +244,8 @@ class CI_Security {
 	/**
 	 * Get CSRF Hash
 	 *
-	 * Getter Method
-	 *
-	 * @return 	string 	self::_csrf_hash
+	 * @see		CI_Security::$_csrf_hash
+	 * @return 	string	CSRF hash
 	 */
 	public function get_csrf_hash()
 	{
@@ -248,9 +257,8 @@ class CI_Security {
 	/**
 	 * Get CSRF Token Name
 	 *
-	 * Getter Method
-	 *
-	 * @return 	string 	self::_csrf_token_name
+	 * @see		CI_Security::$_csrf_token_name
+	 * @return	string	CSRF token name
 	 */
 	public function get_csrf_token_name()
 	{
@@ -263,26 +271,26 @@ class CI_Security {
 	 * XSS Clean
 	 *
 	 * Sanitizes data so that Cross Site Scripting Hacks can be
-	 * prevented.  This function does a fair amount of work but
+	 * prevented.  This method does a fair amount of work but
 	 * it is extremely thorough, designed to prevent even the
 	 * most obscure XSS attempts.  Nothing is ever 100% foolproof,
 	 * of course, but I haven't been able to get anything passed
 	 * the filter.
 	 *
-	 * 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.
+	 * Note: Should only be used to deal with data upon submission.
+	 *	 It's not something that should be used for general
+	 *	 runtime processing.
 	 *
-	 * This function was based in part on some code and ideas I
-	 * got from Bitflux: http://channel.bitflux.ch/wiki/XSS_Prevention
+	 * @link	http://channel.bitflux.ch/wiki/XSS_Prevention
+	 * 		Based in part on some code and ideas from Bitflux.
 	 *
-	 * To help develop this script I used this great list of
-	 * vulnerabilities along with a few other hacks I've
-	 * harvested from examining vulnerabilities in other programs:
-	 * http://ha.ckers.org/xss.html
+	 * @link	http://ha.ckers.org/xss.html
+	 * 		To help develop this script I used this great list of
+	 *		vulnerabilities along with a few other hacks I've
+	 *		harvested from examining vulnerabilities in other programs.
 	 *
-	 * @param	mixed	string or array
-	 * @param 	bool
+	 * @param	string|string[]	$str		Input data
+	 * @param 	bool		$is_image	Whether the input is an image
 	 * @return	string
 	 */
 	public function xss_clean($str, $is_image = FALSE)
@@ -469,9 +477,12 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Random Hash for protecting URLs
+	 * XSS Hash
 	 *
-	 * @return	string
+	 * Generates the XSS hash if needed and returns it.
+	 *
+	 * @see		CI_Security::$_xss_hash
+	 * @return	string	XSS hash
 	 */
 	public function xss_hash()
 	{
@@ -489,7 +500,7 @@ class CI_Security {
 	/**
 	 * HTML Entities Decode
 	 *
-	 * This function is a replacement for html_entity_decode()
+	 * A replacement for html_entity_decode()
 	 *
 	 * The reason we are not using html_entity_decode() by itself is because
 	 * while it is not technically correct to leave out the semicolon
@@ -497,8 +508,10 @@ class CI_Security {
 	 * correctly. html_entity_decode() does not convert entities without
 	 * semicolons, so we are left with our own little solution here. Bummer.
 	 *
-	 * @param	string
-	 * @param	string
+	 * @link	http://php.net/html-entity-decode
+	 *
+	 * @param	string	$str		Input
+	 * @param	string	$charset	Character set
 	 * @return	string
 	 */
 	public function entity_decode($str, $charset = NULL)
@@ -521,10 +534,10 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Filename Security
+	 * Sanitize Filename
 	 *
-	 * @param	string
-	 * @param 	bool
+	 * @param	string	$str		Input file name
+	 * @param 	bool	$relative_path	Whether to preserve paths
 	 * @return	string
 	 */
 	public function sanitize_filename($str, $relative_path = FALSE)
@@ -563,7 +576,7 @@ class CI_Security {
 	/**
 	 * Strip Image Tags
 	 *
-	 * @param	string
+	 * @param	string	$str
 	 * @return	string
 	 */
 	public function strip_image_tags($str)
@@ -576,10 +589,11 @@ class CI_Security {
 	/**
 	 * Compact Exploded Words
 	 *
-	 * Callback function for xss_clean() to remove whitespace from
-	 * things like j a v a s c r i p t
+	 * Callback method for xss_clean() to remove whitespace from
+	 * things like 'j a v a s c r i p t'.
 	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$matches
 	 * @return	string
 	 */
 	protected function _compact_exploded_words($matches)
@@ -593,16 +607,22 @@ class CI_Security {
 	 * Remove Evil HTML Attributes (like event handlers and style)
 	 *
 	 * It removes the evil attribute and either:
-	 * 	- Everything up until a space
-	 *		For example, everything between the pipes:
+	 *
+	 *  - Everything up until a space. For example, everything between the pipes:
+	 *
+	 *	<code>
 	 *		<a |style=document.write('hello');alert('world');| class=link>
-	 * 	- Everything inside the quotes
-	 *		For example, everything between the pipes:
+	 *	</code>
+	 *
+	 *  - Everything inside the quotes. For example, everything between the pipes:
+	 *
+	 *	<code>
 	 *		<a |style="document.write('hello'); alert('world');"| class="link">
+	 *	</code>
 	 *
-	 * @param string $str The string to check
-	 * @param boolean $is_image TRUE if this is an image
-	 * @return string The string with the evil attributes removed
+	 * @param	string	$str		The string to check
+	 * @param	bool	$is_image	Whether the input is an image
+	 * @return	string	The string with the evil attributes removed
 	 */
 	protected function _remove_evil_attributes($str, $is_image)
 	{
@@ -655,9 +675,10 @@ class CI_Security {
 	/**
 	 * Sanitize Naughty HTML
 	 *
-	 * Callback function for xss_clean() to remove naughty HTML elements
+	 * Callback method for xss_clean() to remove naughty HTML elements.
 	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$matches
 	 * @return	string
 	 */
 	protected function _sanitize_naughty_html($matches)
@@ -672,12 +693,14 @@ class CI_Security {
 	/**
 	 * JS Link Removal
 	 *
-	 * Callback function for xss_clean() to sanitize links
+	 * Callback method for xss_clean() to sanitize links.
+	 *
 	 * This limits the PCRE backtracks, making it more performance friendly
 	 * and prevents PREG_BACKTRACK_LIMIT_ERROR from being triggered in
-	 * PHP 5.2+ on link-heavy strings
+	 * PHP 5.2+ on link-heavy strings.
 	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$match
 	 * @return	string
 	 */
 	protected function _js_link_removal($match)
@@ -695,12 +718,14 @@ class CI_Security {
 	/**
 	 * JS Image Removal
 	 *
-	 * Callback function for xss_clean() to sanitize image tags
+	 * Callback method for xss_clean() to sanitize image tags.
+	 *
 	 * This limits the PCRE backtracks, making it more performance friendly
 	 * and prevents PREG_BACKTRACK_LIMIT_ERROR from being triggered in
-	 * PHP 5.2+ on image tag heavy strings
+	 * PHP 5.2+ on image tag heavy strings.
 	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$match
 	 * @return	string
 	 */
 	protected function _js_img_removal($match)
@@ -718,9 +743,8 @@ class CI_Security {
 	/**
 	 * Attribute Conversion
 	 *
-	 * Used as a callback for XSS Clean
-	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$match
 	 * @return	string
 	 */
 	protected function _convert_attribute($match)
@@ -733,9 +757,11 @@ class CI_Security {
 	/**
 	 * Filter Attributes
 	 *
-	 * Filters tag attributes for consistency and safety
+	 * Filters tag attributes for consistency and safety.
 	 *
-	 * @param	string
+	 * @used-by	CI_Security::_js_img_removal()
+	 * @used-by	CI_Security::_js_link_removal()
+	 * @param	string	$str
 	 * @return	string
 	 */
 	protected function _filter_attributes($str)
@@ -757,9 +783,8 @@ class CI_Security {
 	/**
 	 * HTML Entity Decode Callback
 	 *
-	 * Used as a callback for XSS Clean
-	 *
-	 * @param	array
+	 * @used-by	CI_Security::xss_clean()
+	 * @param	array	$match
 	 * @return	string
 	 */
 	protected function _decode_entity($match)
@@ -772,9 +797,8 @@ class CI_Security {
 	/**
 	 * Validate URL entities
 	 *
-	 * Called by xss_clean()
-	 *
-	 * @param 	string
+	 * @used-by	CI_Security::xss_clean()
+	 * @param 	string	$str
 	 * @return 	string
 	 */
 	protected function _validate_entities($str)
@@ -812,8 +836,7 @@ class CI_Security {
 	/**
 	 * Do Never Allowed
 	 *
-	 * A utility function for xss_clean()
-	 *
+	 * @used-by	CI_Security::xss_clean()
 	 * @param 	string
 	 * @return 	string
 	 */
@@ -832,7 +855,7 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set Cross Site Request Forgery Protection Cookie
+	 * Set CSRF Hash and Cookie
 	 *
 	 * @return	string
 	 */