[Sommaire] [Imprimer]

   1  <refentry id="{@id}" revision="$Id: InputFilter.cls 192 2006-03-27 22:02:53Z haas $">
   2   <refnamediv>
   3    <refname>InputFilter</refname>
   4    <refpurpose>Protect Against Malicious SQL and HTML</refpurpose>
   5   </refnamediv>
   6   <refsynopsisdiv>
   7    <author>
   8     Walt Haas
   9     <authorblurb>
  10      {@link mailto:haas@xmission.com haas@xmission.com}
  11     </authorblurb>
  12    </author>
  13   </refsynopsisdiv>
  14   {@toc}
  15   <refsect1 id="{@id intro}">
  16    <title>Introduction</title>
  17    <para>{@link InputFilter} is a
  18    {@link http://en.wikipedia.org/wiki/Singleton_pattern singleton}
  19    class (although not enforced by the constructor) with three public
  20    methods that are useful in protecting  a web site from potential
  21    security threats from user input.</para>
  22    <unorderedlist>
  23     <listitem>{@link InputFilter::safeSQL()} protects SQL from the
  24      user.</listitem> 
  25     <listitem>{@link InputFilter::process()} protects HTML tags and
  26      attributes from the user.</listitem>
  27     <listitem>{@link InputFilter::process_all()} applies
  28      {@link process()} to all possible sources of user input</listitem>
  29    </unorderedlist>
  30   </refsect1>
  31   <refsect1 id="{@id safesql}">
  32    <title>safeSQL(): Protect SQL</title>
  33  
  34    <para>Web site security may be threatened by
  35    {@link http://en.wikipedia.org/wiki/SQL_injection SQL injection}
  36    if a user is allowed to input a query that is not properly screened.
  37    SQL statements are delimited by punctuation characters.  In
  38    particular, the beginning and end of the information being stored or
  39    searched for are delimited by quotes.  If a user is permitted to
  40    include unprotected quotes in their search, there is a danger that
  41    a malicious user might take advantage of this to inject unauthorized
  42    commands into the database.</para>
  43  
  44    <para>To protect against this attack, user information is examined
  45    for quotes and other characters that might be used in an attack, and
  46    every such character is <important>escaped</important> by prefixing
  47    the character with a backslash ('\').  The backslash tells the
  48    database to treat the following character as data, not a
  49    command.</para>
  50  
  51    <para>{@link InputFilter::safeSQL()} may be called as a static
  52    method to screen character strings for threatening characters and
  53    apply the protective backslashes.  An open MySQL connection resource
  54    is needed to establish the appropriate character set.  For
  55    example:</para> 
  56  
  57    <example>
  58  $rs = mysql_connect('hostname', 'username', 'password');
  59  $unsafe = "search term'; drop database employees;";
  60  $protected = InputFilter::safeSQL($unsafe,$rs);
  61  // $protected contains "search term\'; drop database employees;"
  62    </example>
  63   </refsect1>
  64   <refsect1 id="{@id process}">
  65    <title>process(): Protect Against HTML Tags and Attributes</title>
  66  
  67    <para>{@link InputFilter::process()} eliminates potentially
  68    dangerous HTML tags and attributes from its input.  There are
  69    internal lists of
  70    {@link InputFilter::$tagBlacklist blacklisted tags} and
  71    {@link InputFilter::$attrBlacklist blacklisted attributes} than can
  72    optionally be removed from the input.  The constructor also accepts
  73    lists of forbidden tags and attributes and allows the listed names
  74    to be removed, or alternatively to be the only names
  75    accepted.</para>
  76  
  77    <para>To use this method, you must construct an object of the
  78    InputFilter class, with optional behavior specified in the
  79    constructor call. The options are stored as static attributes of the
  80    constructed object, so any reference to an object of the class will
  81    use the attributes in the most recent object.  Therefore it makes
  82    code more readable to use static calls. For example:</para>
  83  
  84    <example>
  85  @new InputFilter();
  86  $output_string = InputFilter::process($input_string);
  87    </example>
  88  
  89    <para>The default constructor, as above, rejects all tags and
  90    attributes, returning only the text between tags.  You can construct
  91    an object which rejects only the blacklisted tags and attributes as
  92    follows:</para>
  93  
  94    <example>
  95  @new InputFilter(array(),array(),1,1,1);
  96    </example>
  97  
  98    <para>You would probably be more secure if you listed what you know
  99    to be safe, instead of trying to think of everything that might
 100    be a threat:</para>
 101    <example>
 102  @new InputFilter(array('div','span','strong','em'),
 103                   array('id','class'),0,0,0);
 104    </example>
 105   </refsect1>
 106   <refsect1 id="{@id process_all}">
 107    <title>process_all(): Protect Against HTML in Request Variables</title>
 108    <para>{@link InputFilter::process()} eliminates potentially
 109    dangerous HTML tags and attributes from the predefined globals
 110    {@link http://www.php.net/reserved.variables#reserved.variables.post $_POST},
 111    {@link http://www.php.net/reserved.variables#reserved.variables.get
 112    $_GET}
 113    and
 114   {@link http://www.php.net/reserved.variables#reserved.variables.request $_REQUEST}.
 115    Call the method statically, as InputFilter::process_all() with the same
 116    arguments as used by {@link InputFilter::__construct() the constructor}.
 117    A new object will be constructed with these options and then
 118    InputFilter::process() will be called on each of $_GET, $_POST and
 119    $_REQUEST.  The options in the call to process_all() are stored as
 120    static attributes of the new object, so they will be used on any calls to
 121    {@link InputFilter::process()} until another object is
 122    constructed.</para>
 123   </refsect1>
 124  <!--
 125  Local variables:
 126  mode: xml
 127  c-basic-offset: 1
 128  indent-tabs-mode: nil
 129  End:
 130  -->
 131  </refentry>