[ci skip] DocBlock improvements for Security library
diff --git a/system/core/Security.php b/system/core/Security.php
index d7c8271..50d0ce0 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
*
- * @var string
+ * Random hash for Cross Site Request Forgery protection cookie
+ *
+ * @var string
*/
protected $_csrf_hash = '';
/**
- * Expiration time for Cross Site Request Forgery Protection Cookie
- * Defaults to two hours (in seconds)
+ * CSRF Expire time
*
- * @var int
+ * Expiration time for Cross Site Request Forgery protection cookie.
+ * Defaults to two hours (in seconds).
+ *
+ * @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
*
- * @var string
+ * Cookie name for Cross Site Request Forgery protection cookie.
+ *
+ * @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 @@
);
/**
- * 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 @@
);
/**
- * Initialize security class
+ * Class constructor
*
* @return void
*/
@@ -138,7 +148,7 @@
// --------------------------------------------------------------------
/**
- * Verify Cross Site Request Forgery Protection
+ * CSRF Verify
*
* @return object
*/
@@ -188,10 +198,10 @@
// --------------------------------------------------------------------
/**
- * Set Cross Site Request Forgery Protection Cookie
+ * CSRF Set Cookie
*
- * @return object
* @codeCoverageIgnore
+ * @return object
*/
public function csrf_set_cookie()
{
@@ -234,9 +244,8 @@
/**
* 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 @@
/**
* 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 @@
* 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 @@
// --------------------------------------------------------------------
/**
- * 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 @@
/**
* 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 @@
* 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 @@
// --------------------------------------------------------------------
/**
- * 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 @@
/**
* Strip Image Tags
*
- * @param string
+ * @param string $str
* @return string
*/
public function strip_image_tags($str)
@@ -576,10 +589,11 @@
/**
* 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 @@
* 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:
- * <a |style=document.write('hello');alert('world');| class=link>
- * - Everything inside the quotes
- * For example, everything between the pipes:
- * <a |style="document.write('hello'); alert('world');"| class="link">
*
- * @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
+ * - Everything up until a space. For example, everything between the pipes:
+ *
+ * <code>
+ * <a |style=document.write('hello');alert('world');| class=link>
+ * </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 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* Do Never Allowed
*
- * A utility function for xss_clean()
- *
+ * @used-by CI_Security::xss_clean()
* @param string
* @return string
*/
@@ -832,7 +855,7 @@
// --------------------------------------------------------------------
/**
- * Set Cross Site Request Forgery Protection Cookie
+ * Set CSRF Hash and Cookie
*
* @return string
*/