Added some docs to CI core files
diff --git a/system/core/Security.php b/system/core/Security.php
old mode 100644
new mode 100755
index 3617cad..dcc680a
--- 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 {
-
- protected $_xss_hash = '';
- protected $_csrf_hash = '';
- protected $_csrf_expire = 7200; // Two hours (in seconds)
- protected $_csrf_token_name = 'ci_csrf_token';
- protected $_csrf_cookie_name = 'ci_csrf_token';
- /* never allowed, string replacement */
+ /**
+ * 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 = '';
+ /**
+ * 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';
+ /**
+ * List of never allowed strings
+ *
+ * @var array
+ * @access protected
+ */
protected $_never_allowed_str = array(
'document.cookie' => '[removed]',
'document.write' => '[removed]',
@@ -46,13 +81,19 @@
);
/* 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 @@
}
// 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 @@
$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 @@
$this->csrf_set_cookie();
log_message('debug', "CSRF token verified ");
-
+
return $this;
}
@@ -146,7 +187,7 @@
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 @@
// --------------------------------------------------------------------
/**
- * Get CSRF Hash
+ * Get CSRF Hash
*
- * Getter Method
+ * Getter Method
*
* @return string self::_csrf_hash
*/
@@ -215,6 +256,7 @@
* 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 @@
*/
$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 @@
*
* 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 @@
*/
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', "<?\\1", $str);
}
@@ -321,10 +363,10 @@
* 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 @@
/*
* 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 @@
/*
* 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 @@
// 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 @@
* Filename Security
*
* @param string
+ * @param bool
* @return string
*/
public function sanitize_filename($str, $relative_path = FALSE)
@@ -542,7 +585,7 @@
"%3b", // ;
"%3d" // =
);
-
+
if ( ! $relative_path)
{
$bad[] = './';
@@ -570,7 +613,7 @@
}
// --------------------------------------------------------------------
-
+
/*
* Remove Evil HTML Attributes (like evenhandlers and style)
*
@@ -578,7 +621,7 @@
* - 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 @@
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 @@
$str, -1, $count
);
} while ($count);
-
+
return $str;
}
-
+
// --------------------------------------------------------------------
/**
@@ -627,7 +670,7 @@
$str = '<'.$matches[1].$matches[2].$matches[3];
// encode captured opening or closing brace to prevent recursive vectors
- $str .= str_replace(array('>', '<'), array('>', '<'),
+ $str .= str_replace(array('>', '<'), array('>', '<'),
$matches[4]);
return $str;
@@ -649,7 +692,7 @@
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 @@
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 @@
}
// --------------------------------------------------------------------
-
+
/**
* Validate URL entities
*
* Called by xss_clean()
*
- * @param string
+ * @param string
* @return string
*/
protected function _validate_entities($str)
@@ -743,9 +786,9 @@
/*
* 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 @@
* Un-Protect GET variables in URLs
*/
$str = str_replace($this->xss_hash(), '&', $str);
-
+
return $str;
}
@@ -794,7 +837,7 @@
{
$str = preg_replace("#".$key."#i", $val, $str);
}
-
+
return $str;
}
@@ -809,16 +852,16 @@
{
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));
}