Show
Ignore:
Timestamp:
02/28/06 12:49:52 (6 years ago)
Author:
haas
Message:

more documentation

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • trunk/trax/vendor/trax/input_filter.php

    r138 r155  
    11<?php 
    2  
    32/** 
    43 *  File containing the InputFilter class 
    … …  
    76 * 
    87 *  @package PHPonTrax 
    9  *  @version 1.2.2_php5 
     8 *  @version $Id$ 
    109 *  @author Daniel Morris 
    1110 *  contributors: Gianpaolo Racca, Ghislain Picard, Marco Wandschneider, 
    … …  
    1615 
    1716/** 
     17 *  Filter user input to remove potential security threats 
    1818 * 
    19  *  @todo Document this class 
    20  *  @package PHPonTrax 
     19 *  InputFilter has three public methods that are useful in protecting 
     20 *  a web site from potential security threats from user input. 
     21 *  <ul> 
     22 *    <li>{@link safeSQL()} protects SQL from the user.</li> 
     23 *    <li>{@link process()} protects HTML tags and attributes from the 
     24 *      user.</li> 
     25 *    <li>{@link process_all()} applies {@link process()} to all 
     26 *      possible sources of user input</li> 
     27 *  </ul> 
     28 *  @todo Check FIXMEs 
    2129 */ 
    2230class InputFilter { 
    2331     
     32    /** 
     33     *  User-provided list of tags to either accept or reject 
     34     * 
     35     *  Whether the tags in this list are accepted or rejected is 
     36     *  determined by the value of {@link $tagsMethod}. 
     37     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     38     *  @var string[] 
     39     */ 
    2440    static protected $tagsArray = array();  // default = empty array 
     41     
     42    /** 
     43     *  User-provided list of attributes to either accept or reject 
     44     * 
     45     *  Whether the attributes in this list are accepted or rejected is 
     46     *  determined by the value of {@link $attrMethod}. 
     47     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     48     *  @var string[] 
     49     */ 
    2550    static protected $attrArray = array();  // default = empty array 
    26  
     51     
     52    /** 
     53     *  How to apply user-provided tags list 
     54     * 
     55     *  Which method to use when applying the list of tags provided by 
     56     *  the user and stored in {@link $tagsArray}. 
     57     *  @var boolean Tested by {@link filterTags()} to see whether the 
     58     *               user-provide list of tags in {@link $tagsArray} 
     59     *               describes those tags which are forbidden, or 
     60     *               those tags which are permitted.  Default false. 
     61     *  <ul> 
     62     *    <li>true =>  Remove  those tags which are in 
     63     *                 {@link $tagsArray}.</li>  
     64     *    <li>false => Allow only those tags which are listed in 
     65     *                 {@link $tagsArray}.</li>  
     66     *  </ul> 
     67     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     68     */ 
    2769    static protected $tagsMethod = 0;   // default = 0 
     70     
     71    /** 
     72     *  How to apply user-provided attribute list 
     73     * 
     74     *  Which method to use when applying the list of attributes 
     75     *  provided by the user and stored in {@link $attrArray}. 
     76     *  @var boolean Tested by {@link filterAttr()} to see whether the 
     77     *               user-provide list of tags in {@link $attrArray} 
     78     *               describes those tags which are forbidden, or 
     79     *               those tags which are permitted.  Default false. 
     80     *  <ul> 
     81     *    <li>true =>  Remove  those tags which are in 
     82     *                 {@link $attrArray}.</li>  
     83     *    <li>false => Allow only those tags which are listed in 
     84     *                 {@link $attrArray}.</li>  
     85     *  </ul> 
     86     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     87     */ 
    2888    static protected $attrMethod = 0;   // default = 0 
    2989 
     90     
     91    /** 
     92     *  Whether to remove blacklisted tags and attributes 
     93     * 
     94     *  @var boolean Tested by {@link filterAttr()} and 
     95     *               {@link filterTags()} to see whether to remove 
     96     *               blacklisted tags and attributes.  Default true. 
     97     *  <ul> 
     98     *    <li>true => Remove tags in {@link $tagBlacklist} and 
     99     *                attributes in {@link $attrBlacklist}, in 
     100     *                addition to all other potentially suspect tags 
     101     *                and attributes.</li> 
     102     *    <li>false => Remove potentially suspect tags and attributes 
     103     *      without consulting{@link $tagBlacklist} or 
     104     *      {@link $attrBlacklist}.</li>  
     105     *  </ul> 
     106     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     107     */ 
    30108    static protected $xssAuto = 1;     // default = 1 
    31     static protected $tagBlacklist = array('applet', 'body', 'bgsound', 'base', 'basefont', 'embed', 'frame', 'frameset', 'head', 'html', 'id', 'iframe', 'ilayer', 'layer', 'link', 'meta', 'name', 'object', 'script', 'style', 'title', 'xml'); 
    32     static protected $attrBlacklist = array('action', 'background', 'codebase', 'dynsrc', 'lowsrc');  // also will strip ALL event handlers 
     109     
     110    /** 
     111     *  List of tags to be removed 
     112     * 
     113     *  If {@link $xssAuto} is true, remove the tags in this list. 
     114     *  @var string[] 
     115     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     116     */ 
     117    static protected $tagBlacklist = 
     118        array('applet', 'body', 'bgsound', 'base', 'basefont', 'embed', 
     119              'frame', 'frameset', 'head', 'html', 'id', 'iframe', 
     120              'ilayer', 'layer', 'link', 'meta', 'name', 'object', 
     121              'script', 'style', 'title', 'xml'); 
     122     
     123    /** 
     124     *  List of attributes to be removed 
     125     * 
     126     *  If {@link $xssAuto} is true, remove the attributes in this list. 
     127     *  @var string[] 
     128     *  <b>FIXME:</b> static declaration must be after visibility declaration 
     129     */ 
     130    static protected $attrBlacklist = 
     131        array('action', 'background', 'codebase', 'dynsrc', 'lowsrc');  
    33132         
    34133    /**  
    35       * Constructor for inputFilter class. Only first parameter is required. 
    36       * 
    37       * @param Array $tagsArray - list of user-defined tags 
    38       * @param Array $attrArray - list of user-defined attributes 
    39       * @param int $tagsMethod - 0= allow just user-defined, 1= allow all but user-defined 
    40       * @param int $attrMethod - 0= allow just user-defined, 1= allow all but user-defined 
    41       * @param int $xssAuto - 0= only auto clean essentials, 1= allow clean blacklisted tags/attr 
    42       */ 
    43     public function __construct($tagsArray = array(), $attrArray = array(), $tagsMethod = 0, $attrMethod = 0, $xssAuto = 1) {        
     134     *  Constructor for InputFilter class. 
     135     * 
     136     *  @param string[] $tagsArray  User-provided list of tags to 
     137     *                              either accept or reject.  Default: none 
     138     *  @param string[] $attrArray  User-provided list of attributes to 
     139     *                              either accept or reject.  Default: none 
     140     *  @param boolean $tagsMethod How to apply the list of tags in $tagsArray: 
     141     *  <ul> 
     142     *    <li>true =>  Remove  those tags which are listed in 
     143     *                 $tagsArray.</li>   
     144     *    <li>false => Allow only those tags which are listed in 
     145     *                 $tagsArray.</li>   
     146     *  </ul> 
     147     *  Default: false 
     148     *  @param boolean $attrMethod How to apply the list of attributess in $attrArray: 
     149     *  <ul> 
     150     *    <li>true =>  Remove  those attributes which are listed in 
     151     *                 $attrArray.</li>   
     152     *    <li>false => Allow only those attributes which are listed in 
     153     *                 $attrArray.</li>   
     154     *  </ul> 
     155     *  Default: false 
     156     *  @param boolean $xssAuto Behavior of {@link filterTags()}: 
     157     *  <ul> 
     158     *    <li>true => Remove tags in {@link $tagBlacklist} and 
     159     *                attributes in {@link $attrBlacklist}, in 
     160     *                addition to all other potentially suspect tags 
     161     *                and attributes.</li> 
     162     *    <li>false => Remove potentially suspect tags and attributes 
     163     *      without consulting{@link $tagBlacklist} or 
     164     *      {@link $attrBlacklist}.</li>  
     165     *  </ul> 
     166     *  Default: true 
     167     *  @uses $attrArray 
     168     *  @uses $attrMethod 
     169     *  @uses $tagsArray 
     170     *  @uses $tagsMethod 
     171     */ 
     172    public function __construct($tagsArray = array(), $attrArray = array(), 
     173                                $tagsMethod = 0, $attrMethod = 0, 
     174                                $xssAuto = 1) {  
    44175        // make sure user defined arrays are in lowercase 
    45176        for ($i = 0; $i < count($tagsArray); $i++) $tagsArray[$i] = strtolower($tagsArray[$i]); 
    … …  
    54185 
    55186    /** 
    56       * Added by John Peterson 
    57       * Method to be called by Trax dispatcher to clean all passed in input. Processes for XSS and specified bad code. 
    58       * @access public 
    59       *  @todo Document this method 
    60       */ 
    61     public function process_all($tagsArray = array(), $attrArray = array(), $tagsMethod = 0, $attrMethod = 0, $xssAuto = 1) { 
    62         self::__construct($tagsArray, $attrArray, $tagsMethod, $attrMethod, $xssAuto); 
     187     *  Remove forbidden tags and attributes from user input 
     188     * 
     189     *  Construct an InputFilter object.  Then apply the 
     190     *  {@link process()} method to each of the user input arrays 
     191     *  {@link http://www.php.net/reserved.variables#reserved.variables.post $_POST}, 
     192     *  {@link http://www.php.net/reserved.variables#reserved.variables.get $_GET} and 
     193     *  {@link http://www.php.net/reserved.variables#reserved.variables.request $_REQUEST}. 
     194     *  <b>FIXME:</b> isn't it partly redundant to do this to $_REQUEST? 
     195     *  Shouldn't we do it to $_COOKIE instead? 
     196     *  @param string[] $tagsArray  User-provided list of tags to 
     197     *                              either accept or reject.  Default: none 
     198     *  @param string[] $attrArray  User-provided list of attributes to 
     199     *                              either accept or reject.  Default: none 
     200     *  @param boolean $tagsMethod How to apply the list of tags in $tagsArray: 
     201     *  <ul> 
     202     *    <li>true =>  Remove  those tags which are listed in 
     203     *                 $tagsArray.</li>   
     204     *    <li>false => Allow only those tags which are listed in 
     205     *                 $tagsArray.</li>   
     206     *  </ul> 
     207     *  Default: false 
     208     *  @param boolean $attrMethod How to apply the list of attributess in $attrArray: 
     209     *  <ul> 
     210     *    <li>true =>  Remove  those attributes which are listed in 
     211     *                 $attrArray.</li>   
     212     *    <li>false => Allow only those attributes which are listed in 
     213     *                 $attrArray.</li>   
     214     *  </ul> 
     215     *  Default: false 
     216     *  @param boolean $xssAuto Behavior of {@link filterTags()}: 
     217     *  <ul> 
     218     *    <li>true => Remove tags in {@link $tagBlacklist} and 
     219     *                attributes in {@link $attrBlacklist}, in 
     220     *                addition to all other potentially suspect tags 
     221     *                and attributes.</li> 
     222     *    <li>false => Remove potentially suspect tags and attributes 
     223     *      without consulting{@link $tagBlacklist} or 
     224     *      {@link $attrBlacklist}.</li>  
     225     *  </ul> 
     226     *  Default: true 
     227     *  @author John Peterson 
     228     *  @uses __construct() 
     229     *  @uses process() 
     230     *  @todo Check out FIXMEs 
     231     */ 
     232    public function process_all($tagsArray = array(), $attrArray = array(), 
     233                                $tagsMethod = 0, $attrMethod = 0, 
     234                                $xssAuto = 1) { 
     235        self::__construct($tagsArray, $attrArray, $tagsMethod, 
     236                          $attrMethod, $xssAuto); 
    63237        if(count($_POST)) { 
    64238            $_POST = self::process($_POST); 
    … …  
    73247     
    74248    /**  
    75       * Method to be called by another php script. Processes for XSS and specified bad code. 
    76       * @access public 
    77       * @param Mixed $source - input string/array-of-string to be 'cleaned' 
    78       * @return String $source - 'cleaned' version of input parameter 
    79       */ 
     249     *  Remove forbidden tags and attributes from array of strings 
     250     * 
     251     *  Accept a string or array of strings.  For each string in the 
     252     *  source, remove the forbidden tags and attributes from the string. 
     253     *  @param mixed $source - input string/array-of-string to be 'cleaned' 
     254     *  @return mixed 'cleaned' version of input parameter 
     255     *  @uses decode() 
     256     *  @uses remove() 
     257     */ 
    80258    public function process($source) { 
    81259        // clean all elements in this array 
    … …  
    97275 
    98276    /**  
    99       * Internal method to iteratively remove all unwanted tags and attributes 
    100       * @access protected 
    101       * @param String $source - input string to be 'cleaned' 
    102       * @return String $source - 'cleaned' version of input parameter 
    103       */ 
     277     *  Remove forbidden tags and attributes from a string iteratively 
     278     * 
     279     *  Call {@link filterTags()} repeatedly until no change in the 
     280     *  input is produced. 
     281     *  @param string $source Input string to be 'cleaned' 
     282     *  @return string 'cleaned' version of $source 
     283     *  @uses filterTags() 
     284     */ 
    104285    protected function remove($source) { 
     286        //  FIXME: what do we use $loopCounter for? 
    105287        $loopCounter=0; 
    106288        // provides nested-tag protection 
    … …  
    113295     
    114296    /**  
    115       * Internal method to strip a string of certain tags 
    116       * @access protected 
    117       * @param String $source - input string to be 'cleaned' 
    118       * @return String $source - 'cleaned' version of input parameter 
    119       */ 
     297     *  Remove forbidden tags and attributes from a string 
     298     * 
     299     *  Inspect the input for tags "<tagname ...>" and check the tag 
     300     *  name against a list of forbidden tag names.  Delete all tags 
     301     *  with forbidden names.  If {@link $xssAuto} is true, delete all 
     302     *  tags in {@link $tagBlacklist}.  If there is a user-defined tag 
     303     *  list in {@link $tagsArray}, process according to the value of 
     304     *  {@link $tagsMethod}. 
     305     * 
     306     *  If the tag name is OK, then call {@link filterAttr()} to check 
     307     *  all attributes of the tag and delete forbidden attributes.  
     308     *  @param string $source Input string to be 'cleaned' 
     309     *  @return string Cleaned version of input parameter 
     310     *  @uses filterAttr() 
     311     *  @uses $tagBlacklist 
     312     *  @uses $tagsArray 
     313     *  @uses $tagsMethod 
     314     *  @uses $xssAuto 
     315     */ 
    120316    protected function filterTags($source) { 
    121317        // filter pass setup 
    … …  
    218414 
    219415    /**  
    220       * Internal method to strip a tag of certain attributes 
    221       * @access protected 
    222       * @param Array $attrSet 
    223       * @return Array $newSet 
    224       */ 
     416     *  Internal method to strip a tag of certain attributes 
     417     * 
     418     *  Remove potentially dangerous attributes from a set of 
     419     *  "attr=value" strings.  Attributes considered dangerous are: 
     420     *  <ul> 
     421     *    <li>Any attribute name containing any non-alphabetic 
     422     *      character</li>  
     423     *    <li>Any attribute name beginning "on..."</li> 
     424     *    <li>If {@link $xssAuto} is true, any attribute name in 
     425     *      {@link $attrBlacklist}</li> 
     426     *    <li>Any attribute with a value containing the strings 
     427     *      'javascript:', 'behaviour:', 'vbscript:', 'mocha:', 
     428     *      'livescript:'</li>  
     429     *    <li>Any attribute whose name contains 'style' and whose 
     430     *      value contains 'expression'.</li> 
     431     *    <li>If there is a user-provided list of attributes in 
     432     *      {@link $attrArray}, process according to the value of 
     433     *      {@link $attrMethod}.</li> 
     434     *  </ul> 
     435     *  @param string[] $attrSet Array of strings "attr=value" parsed 
     436     *                           from a tag. 
     437     *  @return string[] Input with potentially dangerous attributes 
     438     *                   removed 
     439     *  @uses $attrArray 
     440     *  @uses $attrBlacklist 
     441     *  @uses $attrMethod 
     442     *  @uses $xssAuto 
     443     */ 
    225444    protected function filterAttr($attrSet) {    
    226445        $newSet = array(); 
    … …  
    274493     
    275494    /**  
    276       * Try to convert to plaintext 
    277       * @access protected 
    278       * @param String $source 
    279       * @return String $source 
    280       */ 
     495     *  Convert HTML entities to characters 
     496     * 
     497     *  Convert input string containing HTML entities to the 
     498     *  corresponding character (&amp; => &).  ISO 8859-1 character 
     499     *  set is assumed. 
     500     *  @param string $source Character string containing HTML entities 
     501     *  @return string Input string, with entities converted to characters 
     502     *  @uses chr() 
     503     *  @uses html_entity_decode() 
     504     *  @uses preg_replace() 
     505     */ 
    281506    protected function decode($source) { 
    282507        // url decode 
    283508        $source = html_entity_decode($source, ENT_QUOTES, "ISO-8859-1"); 
    284         // convert decimal 
    285         $source = preg_replace('/&#(\d+);/me',"chr(\\1)", $source);             // decimal notation 
    286         // convert hex 
    287         $source = preg_replace('/&#x([a-f0-9]+);/mei',"chr(0x\\1)", $source);   // hex notation 
     509        // convert decimal &#DDD; to character DDD 
     510        $source = preg_replace('/&#(\d+);/me',"chr(\\1)", $source); 
     511        // convert hex &#xXXX; to character XXX 
     512        $source = preg_replace('/&#x([a-f0-9]+);/mei',"chr(0x\\1)", $source); 
    288513        return $source; 
    289514    } 
    290515 
    291516    /**  
    292       * Method to be called by another php script. Processes for SQL injection 
    293       * @access public 
    294       * @param Mixed $source - input string/array-of-string to be 'cleaned' 
    295       * @param Buffer $connection - An open MySQL connection 
    296       * @return String $source - 'cleaned' version of input parameter 
    297       */ 
     517     *  Remove HTML entities and magic quotes, insert SQL special 
     518     *  character escapes 
     519     * 
     520     *  If the input is a string or an array of strings, then each 
     521     *  string is edited to convert any HTML entities to the 
     522     *  corresponding character and remove slashes inserted by 
     523     *  {@link http://www.php.net/manual/en/security.magicquotes.php magic quotes}, 
     524     *  then the result has SQL special characters 
     525     *  escaped. 
     526     *  @param mixed $source Input to be 'cleaned' 
     527     *  @param resource $connection  An open MySQL connection 
     528     *  @return mixed $source with HTML entities and GPC magic quotes 
     529     *                removed from, and SQL special character escapes 
     530     *                inserted in, the string or array of strings. 
     531     *  @uses decode() 
     532     *  @uses quoteSmart() 
     533     */ 
    298534    public function safeSQL($source, &$connection) { 
    299535        // clean all elements in this array 
    … …  
    312548 
    313549    /**  
    314       * @author Chris Tobin 
    315       * @author Daniel Morris 
    316       * @access protected 
    317       * @param String $source 
    318       * @param Resource $connection - An open MySQL connection 
    319       * @return String $source 
    320       */ 
     550     *  Remove GPC magic quotes from input string & escape SQL special 
     551     *  characters 
     552     * 
     553     *  The input is a string that came from a GET or POST HTTP 
     554     *  operation, or a cookie.  If GPC magic quotes are currently in 
     555     *  effect, the resulting slashes are stripped.  Then any SQL 
     556     *  special characters in the string are escaped, taking into 
     557     *  account the character set in use on $connection. 
     558     *  @author Chris Tobin, Daniel Morris 
     559     *  @param string $source Input string to be converted 
     560     *  @param resource $connection An open MySQL connection 
     561     *  @return string Input string with any GPC magic quotes stripped 
     562     *                 and SQL special characters escaped 
     563     *  @uses escapeString() 
     564     *  @uses get_magic_quotes_gpc() 
     565     *  @uses stripslashes() 
     566     */ 
    321567    protected function quoteSmart($source, &$connection) { 
    322568        // strip slashes 
    … …  
    328574     
    329575    /**  
    330       * @author Chris Tobin 
    331       * @author Daniel Morris 
    332       * @access protected 
    333       * @param String $source 
    334       * @param Resource $connection - An open MySQL connection 
    335       * @return String $source 
    336       */     
     576     *  Escape SQL special characters in string 
     577     * 
     578     *  Escape SQL special characters in the input string, taking into 
     579     *  account the character set of the connection. 
     580     * 
     581     *  <b>FIXME:</b> since we require PHP 5 can't we remove the use 
     582     *  of mysql_esacape_string()? 
     583     * 
     584     *  <b>FIXME:</b>Shouldn't we pass the connection to 
     585     *  mysql_real_escape_string()?  
     586     * 
     587     *  <b>FIXME:</b>Is this really RDBMS independent? 
     588     *  @todo Check FIXMEs 
     589     *  @author Chris Tobin, Daniel Morris 
     590     *  @param string $string  String to be protected 
     591     *  @param resource $connection - An open MySQL connection 
     592     *  @return string Value of $string with characters special in 
     593     *                 SQL escaped by '\'s 
     594     *  @uses mysql_escape_string() 
     595     *  @uses mysql_real_escape_string() 
     596     *  @uses phpversion() 
     597     *  @uses version_compare() 
     598     */  
    337599    protected function escapeString($string, &$connection) { 
    338600        // depreciated function 
    … …  
    344606} 
    345607 
     608// -- set Emacs parameters -- 
     609// Local variables: 
     610// tab-width: 4 
     611// c-basic-offset: 4 
     612// c-hanging-comment-ender-p: nil 
     613// indent-tabs-mode: nil 
     614// End: 
    346615?>