Merge pull request #52 from waldmeister/develop

Added some docs to CI core files

1 files changed, 87 insertions, 44 deletions

diff --git a/system/core/Security.php b/system/core/Security.php
index 3617cadcc..dcc680a11 100644..100755
--- a/system/core/Security.php
+++ b/system/core/Security.php
@@ -25,14 +25,49 @@
  * @link		http://codeigniter.com/user_guide/libraries/security.html
  */
 class CI_Security {
-	
+
+	/**
+	 * Random Hash for protecting URLs
+	 *
+	 * @var string
+	 * @access protected
+	 */
 	protected $_xss_hash			= '';
+	/**
+	 * Random Hash for Cross Site Request Forgery Protection Cookie
+	 *
+	 * @var string
+	 * @access protected
+	 */
 	protected $_csrf_hash			= '';
-	protected $_csrf_expire			= 7200;  // Two hours (in seconds)
+	/**
+	 * Expiration time for Cross Site Request Forgery Protection Cookie
+	 * Defaults to two hours (in seconds)
+	 *
+	 * @var int
+	 * @access protected
+	 */
+	protected $_csrf_expire			= 7200;
+	/**
+	 * Token name for Cross Site Request Forgery Protection Cookie
+	 *
+	 * @var string
+	 * @access protected
+	 */
 	protected $_csrf_token_name		= 'ci_csrf_token';
+	/**
+	 * Cookie name for Cross Site Request Forgery Protection Cookie
+	 *
+	 * @var string
+	 * @access protected
+	 */
 	protected $_csrf_cookie_name	= 'ci_csrf_token';
-
-	/* never allowed, string replacement */
+	/**
+	 * List of never allowed strings
+	 *
+	 * @var array
+	 * @access protected
+	 */
 	protected $_never_allowed_str = array(
 					'document.cookie'	=> '[removed]',
 					'document.write'	=> '[removed]',
@@ -46,13 +81,19 @@ class CI_Security {
 	);
 
 	/* never allowed, regex replacement */
+	/**
+	 * List of never allowed regex replacement
+	 *
+	 * @var array
+	 * @access protected
+	 */
 	protected $_never_allowed_regex = array(
 					"javascript\s*:"			=> '[removed]',
 					"expression\s*(\(|&\#40;)"	=> '[removed]', // CSS and IE
 					"vbscript\s*:"				=> '[removed]', // IE, surprise!
 					"Redirect\s+302"			=> '[removed]'
 	);
-	
+
 	/**
 	 * Constructor
 	 */
@@ -95,7 +136,7 @@ class CI_Security {
 		}
 
 		// Do the tokens exist in both the _POST and _COOKIE arrays?
-		if ( ! isset($_POST[$this->_csrf_token_name]) OR 
+		if ( ! isset($_POST[$this->_csrf_token_name]) OR
 			 ! isset($_COOKIE[$this->_csrf_cookie_name]))
 		{
 			$this->csrf_show_error();
@@ -107,7 +148,7 @@ class CI_Security {
 			$this->csrf_show_error();
 		}
 
-		// We kill this since we're done and we don't want to 
+		// We kill this since we're done and we don't want to
 		// polute the _POST array
 		unset($_POST[$this->_csrf_token_name]);
 
@@ -117,7 +158,7 @@ class CI_Security {
 		$this->csrf_set_cookie();
 
 		log_message('debug', "CSRF token verified ");
-		
+
 		return $this;
 	}
 
@@ -146,7 +187,7 @@ class CI_Security {
 		setcookie($this->_csrf_cookie_name, $this->_csrf_hash, $expire, config_item('cookie_path'), config_item('cookie_domain'), $secure_cookie);
 
 		log_message('debug', "CRSF cookie Set");
-		
+
 		return $this;
 	}
 
@@ -165,9 +206,9 @@ class CI_Security {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Get CSRF Hash 
+	 * Get CSRF Hash
 	 *
-	 * Getter Method 
+	 * Getter Method
 	 *
 	 * @return 	string 	self::_csrf_hash
 	 */
@@ -215,6 +256,7 @@ class CI_Security {
 	 * http://ha.ckers.org/xss.html
 	 *
 	 * @param	mixed	string or array
+	 * @param 	bool
 	 * @return	string
 	 */
 	public function xss_clean($str, $is_image = FALSE)
@@ -263,7 +305,7 @@ class CI_Security {
 		 */
 
 		$str = preg_replace_callback("/[a-z]+=([\'\"]).*?\\1/si", array($this, '_convert_attribute'), $str);
-	
+
 		$str = preg_replace_callback("/<\w+.*?(?=>|<|$)/si", array($this, '_decode_entity'), $str);
 
 		/*
@@ -276,7 +318,7 @@ class CI_Security {
 		 *
 		 * This prevents strings like this: ja	vascript
 		 * NOTE: we deal with spaces between characters later.
-		 * NOTE: preg_replace was found to be amazingly slow here on 
+		 * NOTE: preg_replace was found to be amazingly slow here on
 		 * large blocks of data, so we use str_replace.
 		 */
 
@@ -304,8 +346,8 @@ class CI_Security {
 		 */
 		if ($is_image === TRUE)
 		{
-			// Images have a tendency to have the PHP short opening and 
-			// closing tags every so often so we skip those and only 
+			// Images have a tendency to have the PHP short opening and
+			// closing tags every so often so we skip those and only
 			// do the long opening tags.
 			$str = preg_replace('/<\?(php)/i', "&lt;?\\1", $str);
 		}
@@ -321,10 +363,10 @@ class CI_Security {
 		 * These words are compacted back to their correct state.
 		 */
 		$words = array(
-				'javascript', 'expression', 'vbscript', 'script', 
+				'javascript', 'expression', 'vbscript', 'script',
 				'applet', 'alert', 'document', 'write', 'cookie', 'window'
 			);
-			
+
 		foreach ($words as $word)
 		{
 			$temp = '';
@@ -341,8 +383,8 @@ class CI_Security {
 
 		/*
 		 * Remove disallowed Javascript in links or img tags
-		 * We used to do some version comparisons and use of stripos for PHP5, 
-		 * but it is dog slow compared to these simplified non-capturing 
+		 * We used to do some version comparisons and use of stripos for PHP5,
+		 * but it is dog slow compared to these simplified non-capturing
 		 * preg_match(), especially if the pattern exists in the string
 		 */
 		do
@@ -405,11 +447,11 @@ class CI_Security {
 
 		/*
 		 * Images are Handled in a Special Way
-		 * - Essentially, we want to know that after all of the character 
-		 * conversion is done whether any unwanted, likely XSS, code was found.  
+		 * - Essentially, we want to know that after all of the character
+		 * conversion is done whether any unwanted, likely XSS, code was found.
 		 * If not, we return TRUE, as the image is clean.
-		 * However, if the string post-conversion does not matched the 
-		 * string post-removal of XSS, then it fails, as there was unwanted XSS 
+		 * However, if the string post-conversion does not matched the
+		 * string post-removal of XSS, then it fails, as there was unwanted XSS
 		 * code found and removed/changed during processing.
 		 */
 
@@ -478,7 +520,7 @@ class CI_Security {
 		// correctly.  html_entity_decode() does not convert entities without
 		// semicolons, so we are left with our own little solution here. Bummer.
 
-		if (function_exists('html_entity_decode') && 
+		if (function_exists('html_entity_decode') &&
 			(strtolower($charset) != 'utf-8'))
 		{
 			$str = html_entity_decode($str, ENT_COMPAT, $charset);
@@ -505,6 +547,7 @@ class CI_Security {
 	 * Filename Security
 	 *
 	 * @param	string
+	 * @param 	bool
 	 * @return	string
 	 */
 	public function sanitize_filename($str, $relative_path = FALSE)
@@ -542,7 +585,7 @@ class CI_Security {
 						"%3b",		// ;
 						"%3d"		// =
 					);
-		
+
 		if ( ! $relative_path)
 		{
 			$bad[] = './';
@@ -570,7 +613,7 @@ class CI_Security {
 	}
 
 	// --------------------------------------------------------------------
-	
+
 	/*
 	 * Remove Evil HTML Attributes (like evenhandlers and style)
 	 *
@@ -578,7 +621,7 @@ class CI_Security {
 	 * 	- Everything up until a space
 	 *		For example, everything between the pipes:
 	 *		<a |style=document.write('hello');alert('world');| class=link>
-	 * 	- Everything inside the quotes 
+	 * 	- Everything inside the quotes
 	 *		For example, everything between the pipes:
 	 *		<a |style="document.write('hello'); alert('world');"| class="link">
 	 *
@@ -594,12 +637,12 @@ class CI_Security {
 		if ($is_image === TRUE)
 		{
 			/*
-			 * Adobe Photoshop puts XML metadata into JFIF images, 
+			 * Adobe Photoshop puts XML metadata into JFIF images,
 			 * including namespacing, so we have to allow this for images.
 			 */
 			unset($evil_attributes[array_search('xmlns', $evil_attributes)]);
 		}
-		
+
 		do {
 			$str = preg_replace(
 				"#<(/?[^><]+?)([^A-Za-z\-])(".implode('|', $evil_attributes).")(\s*=\s*)([\"][^>]*?[\"]|[\'][^>]*?[\']|[^>]*?)([\s><])([><]*)#i",
@@ -607,10 +650,10 @@ class CI_Security {
 				$str, -1, $count
 			);
 		} while ($count);
-		
+
 		return $str;
 	}
-	
+
 	// --------------------------------------------------------------------
 
 	/**
@@ -627,7 +670,7 @@ class CI_Security {
 		$str = '&lt;'.$matches[1].$matches[2].$matches[3];
 
 		// encode captured opening or closing brace to prevent recursive vectors
-		$str .= str_replace(array('>', '<'), array('&gt;', '&lt;'), 
+		$str .= str_replace(array('>', '<'), array('&gt;', '&lt;'),
 							$matches[4]);
 
 		return $str;
@@ -649,7 +692,7 @@ class CI_Security {
 	protected function _js_link_removal($match)
 	{
 		$attributes = $this->_filter_attributes(str_replace(array('<', '>'), '', $match[1]));
-		
+
 		return str_replace($match[1], preg_replace("#href=.*?(alert\(|alert&\#40;|javascript\:|livescript\:|mocha\:|charset\=|window\.|document\.|\.cookie|<script|<xss|base64\s*,)#si", "", $attributes), $match[0]);
 	}
 
@@ -669,7 +712,7 @@ class CI_Security {
 	protected function _js_img_removal($match)
 	{
 		$attributes = $this->_filter_attributes(str_replace(array('<', '>'), '', $match[1]));
-		
+
 		return str_replace($match[1], preg_replace("#src=.*?(alert\(|alert&\#40;|javascript\:|livescript\:|mocha\:|charset\=|window\.|document\.|\.cookie|<script|<xss|base64\s*,)#si", "", $attributes), $match[0]);
 	}
 
@@ -729,13 +772,13 @@ class CI_Security {
 	}
 
 	// --------------------------------------------------------------------
-	
+
 	/**
 	 * Validate URL entities
 	 *
 	 * Called by xss_clean()
 	 *
-	 * @param 	string	
+	 * @param 	string
 	 * @return 	string
 	 */
 	protected function _validate_entities($str)
@@ -743,9 +786,9 @@ class CI_Security {
 		/*
 		 * Protect GET variables in URLs
 		 */
-		
+
 		 // 901119URL5918AMP18930PROTECT8198
-		
+
 		$str = preg_replace('|\&([a-z\_0-9\-]+)\=([a-z\_0-9\-]+)|i', $this->xss_hash()."\\1=\\2", $str);
 
 		/*
@@ -769,7 +812,7 @@ class CI_Security {
 		 * Un-Protect GET variables in URLs
 		 */
 		$str = str_replace($this->xss_hash(), '&', $str);
-		
+
 		return $str;
 	}
 
@@ -794,7 +837,7 @@ class CI_Security {
 		{
 			$str = preg_replace("#".$key."#i", $val, $str);
 		}
-		
+
 		return $str;
 	}
 
@@ -809,16 +852,16 @@ class CI_Security {
 	{
 		if ($this->_csrf_hash == '')
 		{
-			// If the cookie exists we will use it's value.  
+			// If the cookie exists we will use it's value.
 			// We don't necessarily want to regenerate it with
-			// each page load since a page could contain embedded 
+			// each page load since a page could contain embedded
 			// sub-pages causing this feature to fail
-			if (isset($_COOKIE[$this->_csrf_cookie_name]) && 
+			if (isset($_COOKIE[$this->_csrf_cookie_name]) &&
 				$_COOKIE[$this->_csrf_cookie_name] != '')
 			{
 				return $this->_csrf_hash = $_COOKIE[$this->_csrf_cookie_name];
 			}
-			
+
 			return $this->_csrf_hash = md5(uniqid(rand(), TRUE));
 		}