0byt3m1n1
Path:
/
data
/
applications
/
aps.bak
/
coppermine
/
1.5.12-0
/
standard
/
htdocs
/
docs
/
fr
/
[
Home
]
File: dev_superglobals.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr"> <head> <title>Sanitization of Superglobals using Inspekt - Coppermine Photo Gallery - Documentation & Manual</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="language" content="en" /> <meta name="copyright" content="Coppermine dev team" /> <meta name="description" content="list of plugin hooks" /> <meta http-equiv="Content-Style-Type" content="text/css" /> <meta name="MSSmartTagsPreventParsing" content="true" /> <meta http-equiv="imagetoolbar" content="no" /> <!-- SVN version info: Coppermine version: 1.5.12 $HeadURL: https://coppermine.svn.sourceforge.net/svnroot/coppermine/trunk/cpg1.5.x/docs/fr/dev_superglobals.htm $ $Revision: 8154 $ $Date: 2011-01-02 20:44:22 +0100 (So, 02 Jan 2011) $ --> <link rel="stylesheet" type="text/css" href="../style/style.css" media="all" /> <link rel="stylesheet" type="text/css" href="../style/screen.css" media="screen" /> <link rel="stylesheet" type="text/css" href="../style/print.css" media="print" /> <link rel="shortcut icon" href="../favicon.ico" /> <script src="../js/jquery.js" type="text/javascript"></script> <script src="../js/jquery.treeview.js" type="text/javascript"></script> <script src="script.js" type="text/javascript"></script> </head> <body> <h1 id="docheader">Coppermine Photo Gallery v1.5.x: Documentation and Manual</h1> <div id="toc"> <a href="toc.htm">Table of Contents</a> </div> <div id="doc_en_only">No translation available</div> <a name="superglobals_sanitization"></a><h1>Sanitization of Superglobals using Inspekt<a href="#superglobals_sanitization" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h1> <a name="superglobals_sanitization_target_audience"></a><h2>Target audience<a href="#superglobals_sanitization_target_audience" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>This part of the documentation is not meant for end users of Coppermine, but only for developers and skilled users who are familiar with coding. There is no support for this section, it comes as-is.</p> <p>For coppermine dev team members, this piece of documentation is meant both as a reference as well as a programming guideline.</p> <p>For users, this section can be helpful if you want to modify your coppermine gallery and want to come up with additional functionality and use superglobals (like <tt class="code">$_GET</tt> and <tt class="code">$_POST</tt> variables) in those custom scripts.</p> <a name="superglobals_sanitization_whats_new"></a><h2>What's new?<a href="#superglobals_sanitization_whats_new" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>Starting with cpg1.5.0 the individual components of coppermine (the script files like displayimage.php) can no longer access <a href="http://www.php.net/manual/en/language.variables.predefined.php#language.variables.superglobals" rel="externals" class="phpnet">superglobals</a> like <tt class="code">$_GET</tt> or <tt class="code">$_POST</tt> directly. Those superglobals are being put into a "cage" object instead when the Coppermine basic includes get started and all vars and function are being initialized. Once the "cage" has been populated, the superglobals get emptied and can therefore no longer be accessed. Subsequently, you can no longer use the superglobals as you might be used to. Confused? Read on.</p> <a name="superglobals_sanitization_reason"></a><h2>Reason<a href="#superglobals_sanitization_reason" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>Everyone knows that you should filter your inputs - most of the good programmers do it, but when you are working with a large team of programmers on an open source project things slip up, errors do creep in, at times like this you wish for a mechanism which would prevent your team from making such mistakes, some thing which forces them to declare their intent.</p> <p>Most of the vulnerabilities that have been discovered in cpg1.4.x where caused by user input not properly sanitized, which led to <acronym title="Cross Site Scripting">XSS</acronym> attacks becoming possible. In an effort to improve the security behind coppermine thoroughly the dev team has decided to sanitize all superglobals using the tool "<a href="http://code.google.com/p/inspekt/" rel="external" class="external">Inspekt</a>" (which is being released under the <a href="http://www.opensource.org/licenses/bsd-license.php" rel="external" class="external">BSD license</a> and can therefore be included without issues into the coppermine core code license-wise).</p> <p>The idea to use Inspekt has been brought up by Coppermine lead developer Dr. Tarique Sani in his blog article "<a href="http://www.sanisoft.com/blog/2007/10/15/inspekt-put-a-firewall-in-your-php-applications/" rel="external" class="external">Inspekt - put a firewall in your PHP applications</a>", where he discusses the reasons to use Inspekt in detail.</p> <a name="superglobals_sanitization_about_inspekt"></a><h2>What Inspekt does<a href="#superglobals_sanitization_about_inspekt" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>Inspekt acts as a sort of 'firewall' API between user input and the rest of the application. It takes PHP superglobal arrays, encapsulates their data in an "cage" object, and destroys the original superglobal. Data can then be retrieved from the input data object using a variety of accessor methods that apply filtering, or the data can be checked against validation methods. Raw data can only be accessed via a <tt class="code">getRaw()</tt> method, forcing the developer to show clear intent. Read more about usage on the <a href="http://code.google.com/p/inspekt/wiki/BasicUsage" rel="external" class="external">Inspect Wiki: Basic Usage</a>.</p> <div class"=indent"> <a name="superglobals_sanitization_inspekt_accessor_methods"></a><h3>Inspekt accessor methods<a href="#superglobals_sanitization_inspekt_accessor_methods" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>One thing which is missing from the Inspekt Wiki page is the list of accessor methods. In brief they are:</p> <ul> <li><tt class="code">getAlnum</tt> - Returns only the alphabetic characters and digits in value.</li> <li><tt class="code">getAlpha</tt> - Returns only the alphabetic characters in value.</li> <li><tt class="code">getDigits</tt> - Returns only the digits in value. This differs from getInt().</li> <li><tt class="code">getDir</tt> - Returns dirname(value).</li> <li><tt class="code">getInt</tt> - Returns (int) value.</li> <li><tt class="code">getPath</tt> - Returns realpath(value).</li> <li><tt class="code">getEscaped</tt> - Returns the requested value with mysql_real_escape taking into account the magic quotes gpc setting.<br /> Getting a properly escaped value serves the purpose of preventing to a degree the SQL injection possibilities - it is to be used in places where we were previously using addslashes. If sanitization is needed for user input it should be <em>before</em> escaping and not after it.</li> <li><tt class="code">getMatched</tt> - Returns an array of matches against a regex for a given value. If a match fails false is returned.</li> <li><tt class="code">getRaw</tt> - Returns the Raw value.</li> </ul> <p>Care should be taken to as far as possible not use the getRaw() method - if it is used then please comment profusely as to why it is safe to use getRaw in the given circumstances (e.g.: the same value was tested against a regex before fetching or the value is sanitized immediately after getting). If there case where getRaw() cannot be avoided but is still unsafe please comment on possible solutions. Once again - the final aim is to NOT use getRaw() at all.</p> </div> <a name="superglobals_sanitization_howto"></a><h2>How to use Inspekt with Coppermine Photo Gallery<a href="#superglobals_sanitization_howto" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <p>Inspekt provides tools for filtering scalar or array data in two ways:</p> <ul> <li>Cage objects that encapsulate an array and provide accessor methods that force filtering and/or validation - Special helper methods allow you to set up cages on the input superglobals with one method call</li> <li>Static filters and validators for arbitrary scalar or array data</li> </ul> <p>The guiding principle for Inspekt is to make it easier to create secure PHP applications. As such, ease of use is valued over flexibility, and verbosity is avoided when possible.</p> <div class="indent"> <a name="superglobals_sanitization_howto_using"></a><h3>Using Inspekt<a href="#superglobals_sanitization_howto_using" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <pre class="cpg_code">// Example: creating a cage for $_POST require_once "Inspekt.php"; $cage_POST = Inspekt::makePostCage(); $userid = $cage_POST->getInt('userid'); if ( !isset($_POST['userid']) ) { echo 'Cannot access input via $_POST -- use the cage object'; }</pre> <p>We can see from the above example that after making a cage for <tt class="code">$_POST</tt>, it is not accessible directly. One must use the methods provided by Inspekt to get the data in correct data type and format.</p> <a name="superglobals_sanitization_howto_inspekt_in_coppermine"></a><h3>Inspekt in Coppermine<a href="#superglobals_sanitization_howto_inspekt_in_coppermine" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>Inspekt has been used in CPG by including it in init.inc.php file at the very beginning and creating a <strong>supercage</strong> immediately after its inclusion.</p> <pre class="cpg_code">set_include_path(get_include_path().PATH_SEPARATOR.dirname(__FILE__).PATH_SEPARATOR.'Inspekt'); echo dirname(__FILE__); require_once "Inspekt.php"; $superCage = Inspekt::makeSuperCage();</pre> <p>Supercage is an aggregation of all the cages, i.e <acronym title="Environment, Get, Post, Cookie, Server">EGPCS</acronym> (the order of variable parsing). Once the supercage is created none of the EGPCS variables are available.</p> <p>To access a variable within a supercage we have to use the following format:</p> <pre class="cpg_code">$qs = $superCage->server->getDigits('QUERY_STRING'); $album_id = $superCage->get->getInt('album'); $title = $superCage->post->getAlpha('title');</pre> <p class="cpg_message_success">To get an instance of <tt class="code">$superCage</tt> inside a function use <tt class="code">$superCage = Inspekt::makeSuperCage();</tt> again. Do not use the global directive. It may be noted here that <tt class="code">makeSuperCage()</tt> creates a singleton pattern object. So calling it multiple times does not have any overheads and you can be assured of getting the very same object every time.</p> <p>In other words - you don't have to take care not to define <tt class="code">$superCage</tt> - it doesn't hurt to call it many times over. Don't bloat the code by assigning other names:</p> <table cellspacing="0" cellpadding="0" border="0" width="100%" class="maintable"> <tr> <th class="tableh1" width="50%"> Bad example </th> <th class="tableh1" width="50%"> Good example </th> </tr> <tr> <td class="cpg_message_error code"> <tt class="code">$yetAnotherCage = Inspekt::makeSuperCage();</tt> </td> <td class="cpg_message_success"> <tt class="code">$superCage = Inspekt::makeSuperCage();</tt> </td> </tr> </table> <p>Every dev is encouraged to download the latest tarball of Inspekt and checkout the API documentation for the list of <a href="#superglobals_sanitization_inspekt_accessor_methods">available methods for accessing data from cages</a>. In addition to this, there is a bunch of test functions which will test a value of a given key against a pre-determined datatype or format.</p> <a name="superglobals_sanitization_howto_consider_methods"></a><h3>Consider the methods to use<a href="#superglobals_sanitization_howto_consider_methods" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>Before using a particular method, make up your mind what kind of data you expect to retrieve: is the data you expect just an integer (e.g. "0" or "1" used in a parameter to toggle an option on or off) - then use <tt class="code">getInt</tt>. Do you expect an alphanumeric string (with only alphanumeric data, no spaces, no special chars nor non-latin characters), like the parameter of a pre-determined action (e.g. "delete", "update" or "add"), then use <tt class="code">getAlnum</tt> or <tt class="code">getAlpha</tt>. If the parameter you're trying to fetch <em>may</em> contain something else (e.g. a filename that may only contain latin characters, but that may as well contain utf-8 encoded non-latin characters like Umlauts), then use getMatched and perform a match against a regular expression - you may even have to sanitize the value even more after fetching it.</p> <a name="superglobals_sanitization_howto_examples"></a><h3>Examples<a href="#superglobals_sanitization_howto_examples" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>Here are some real-world examples of how code used to look initially (before Inspekt was introduced) and what was changed to make it work with Inspekt.</p> <table border="0" cellspacing="0" cellpadding="0" class="cpg_zebra"> <tr> <th valign="top" align="left">File</th> <th valign="top" align="left">Before implementing Inspekt</th> <th valign="top" align="left">After implementing Inspekt</th> </tr> <tr> <td valign="top">albmgr.php</td> <td valign="top"> <pre>$CLEAN['cat'] = isset($_GET['cat']) ? (int)($_GET['cat']) : 0;</pre> [...] <pre>$cat = $CLEAN['cat'];</pre> </td> <td valign="top"> <pre> </pre> [...] <pre>if ($superCage->get->keyExists('cat')) { $cat = $superCage->get->getInt('cat'); } else { $cat = 0; }</pre> </td> </tr> <tr> <td valign="top">calendar.php</td> <td valign="top"> <pre>if ($_REQUEST['action'] == 'browsebydate') {</pre> [...] <pre>$month = (int) $_REQUEST['month']; $year = (int) $_REQUEST['year'];</pre> </td> <td valign="top"> <pre>if ($matches = $superCage->get->getMatched('action', '/^[a-z]+$/')) { $action = $matches[0]; } elseif ($matches = $superCage->post->getMatched('action', '/^[a-z]+$/')) { $action = $matches[0]; } else { $action = ''; } if ($action == 'browsebydate') {</pre> [...] <pre>if ($superCage->get->testInt('month')) { $month = $superCage->get->getInt('month'); } elseif ($superCage->post->testInt('month')) { $month = $superCage->post->getInt('month'); } else { $month = 0; } if ($superCage->get->testInt('year')) { $year = $superCage->get->getInt('year'); } elseif ($superCage->post->testInt('year')) { $year = $superCage->post->getInt('year'); } else { $year = 0; }</pre> </td> </tr> <tr> <td valign="top">getlang.php</td> <td valign="top"> <pre>if (isset($_GET['get'])) { $file_index = (int)$_GET['get'];</pre> [...] <pre><img src="images/folder.gif" alt="">&nbsp;<a href="{$_SERVER['PHP_SELF']}?get=$index">$file</a></pre> </td> <td valign="top"> <pre>if ($superCage->get->keyExists('get')) { $file_index = $superCage->get->getInt('get') ;</pre> [...] <pre><img src="images/folder.gif" alt="">&nbsp;<a href="{$CPG_PHP_SELF}?get=$index">$file</a></pre> </td> </tr> </table> <a name="superglobals_sanitization_howto_regex"></a><h3>Regular Expressions (regex)<a href="#superglobals_sanitization_howto_regex" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h3> <p>The method <tt class="code">getMatched</tt> makes use of regular expressions that can be tricky for beginners. It would be beyond the scope of this documentation to explain how regular expressions work in detail - we just added some "typical" regular expressions that you can use in your own code:</p> <table border="0" cellspacing="0" cellpadding="0" class="cpg_zebra"> <tr> <th valign="top" align="left">Regex</th> <th valign="top" align="left">Description</th> <th valign="top" align="left">Example</th> </tr> <tr> <td valign="top"> <tt class="code">/^[0-9a-z]+$/</tt> </td> <td valign="top"> Will match lower-case alpha-numerals </td> <td valign="top"> </td> </tr> <tr> <td valign="top"> <tt class="code">/^[0-9A-A]+$/</tt> </td> <td valign="top"> Will match upper-case alpha-numerals </td> <td valign="top"> </td> </tr> <tr> <td valign="top"> <tt class="code">/^[0-9A-Za-z]+$/</tt> </td> <td valign="top"> Will match alpha-numerals (case-insensitive) </td> <td valign="top"> </td> </tr> <tr> <td valign="top"> <tt class="code">/^[0-9A-Za-z]{3,6}$/</tt> </td> <td valign="top"> Will match alpha-numerals (case-insensitive) with a minimum of 3 characters and a maximum of 6 </td> <td valign="top"> </td> </tr> <tr> <td valign="top"> <tt class="code">/^[a-z_]+$/</tt> </td> <td valign="top"> Will match lower case letters and an underscore, e.g. strings like 'foo' or 'foo_bar' </td> <td valign="top"> </td> </tr> <tr> <td valign="top"><tt class="code">/^[0-9A-Za-z_]+$/</tt></td> <td valign="top">Alphanumerals (numbers and latin characters) both in lower as well as upper case and the special char "underscore" (<tt class="code">_</tt>) will match (i.e. return TRUE)</td> <td valign="top">'<tt class="code">foobar</tt>', '<tt class="code">fooBar</tt>', '<tt class="code">foo_bar</tt>', '<tt class="code">foobar_</tt>', '<tt class="code">2foo3bar</tt>' will match (true).<br />'<tt class="code">fübar</tt>', '<tt class="code">foo-bar</tt>', '<tt class="code">foo bar</tt>' will not match (false)</td> </tr> <tr> <td valign="top"><tt class="code">/^[a-zA-Z0-9_\-]*$/</tt></td> <td valign="top">Alphanumerals (numbers and latin characters) both in lower as well as upper case and the special char "underscore" (<tt class="code">_</tt>) and the dash (<tt class="code">-</tt>) will match (i.e. return TRUE)</td> <td valign="top">'<tt class="code">foobar</tt>', '<tt class="code">fooBar</tt>', '<tt class="code">foo_bar</tt>', '<tt class="code">foobar_</tt>', '<tt class="code">2foo3bar</tt>', '<tt class="code">foo-bar</tt>' will match (true).</td> </tr> <tr> <td valign="top"><tt class="code">/^[a-z]*$/</tt></td> <td valign="top">Only latin character in lowercase will match.</td> <td valign="top">'<tt class="code">foobar</tt>' will match (true).<br />'<tt class="code">fooBar</tt>', '<tt class="code">foo5bar</tt>', '<tt class="code">foo-bar</tt>', '<tt class="code">foo bar</tt>' will not match (false)</td> </tr> <tr> <td valign="top"><tt class="code">/^[a-zA-Z0-9]*$/</tt></td> <td valign="top">Alphanumerals (numbers and latin characters) both in lower as well as upper case will match (i.e. return TRUE). However, you could use the method <tt class="code">getAlnum</tt> just as well - it will make the code more readable and easier to understand for others.</td> <td valign="top">'<tt class="code">foobar</tt>', '<tt class="code">fooBar</tt>', '<tt class="code">2foo3bar</tt>' will match (true).<br />'<tt class="code">fübar</tt>', '<tt class="code">foo_bar</tt>', '<tt class="code">foo-bar</tt>', '<tt class="code">foo bar</tt>', '<tt class="code">foobar_</tt>' will not match (false)</td> </tr> <tr> <td valign="top"><tt class="code">/^\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b$/</tt></td> <td valign="top">IP addresses (v4) will match (return TRUE).</td> <td valign="top">'<tt class="code">1.2.3.4</tt>', '<tt class="code">192.168.0.1</tt>' will match (true).<br />'<tt class="code">1.2.3</tt>', '<tt class="code">1.2.3.4.5</tt>', '<tt class="code">192.168.0.10/2</tt>', '<tt class="code">coppermine-gallery.net</tt>', '<tt class="code">192.168.0.300</tt>' will not match (false)</td> </tr> <tr> <td valign="top"><tt class="code">/^([a-zA-Z0-9]((\.|\-|\_){0,1}[a-zA-Z0-9]){0,})@([a-zA-Z]((\.|\-){0,1}[a-zA-Z0-9]){0,})\.([a-zA-Z]{2,4})$/</tt></td> <td valign="top">Valid email addresses will match (i.e. return TRUE). However, this regex does not check if the domain exists nor if the <abbr title="Top Level Domain">TLD</abbr> is valid.</td> <td valign="top">'<tt class="code">john.doe@example.com</tt>', '<tt class="code">john@example.com</tt>', '<tt class="code">john-doe@some.example.com</tt>' will match (true).<br />'<tt class="code">john.doe</tt>', '<tt class="code">john.doe@</tt>', '<tt class="code">@example.com</tt>', '<tt class="code">jürgen.doe@example.com</tt>', '<tt class="code">john=doe@example.com</tt>' will not match (false)</td> </tr> <tr> <td valign="top"> <tt class="code">/^[+-]?([0-9]{1,2})*\.?[0-9]+$/</tt> </td> <td valign="top"> Will allow you to enter integers between 0 and 999 with or without a trailing percent sign, which can be helpfull if you want to allow dimensions (for HTML/CSS attributes) in pixels or percent </td> <td valign="top"> </td> </tr> <tr> <td valign="top"> <tt class="code">/^#(?:(?:[a-f\d]{3}){1,2})$/i</tt> </td> <td valign="top"> Will match valid RGB color codes from #000000 to #FFFFFF </td> <td valign="top"> </td> </tr> </table> </div> <a name="superglobals_sanitization_links"></a><h2>Links<a href="#superglobals_sanitization_links" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2> <ul> <li><a href="http://code.google.com/p/inspekt/" rel="external" class="external">Inspekt project pages</a><br /> <ul> <li><a href="http://code.google.com/p/inspekt/wiki/BasicUsage" rel="external" class="external">Inspekt Wiki: BasicUsage</a></li> <li><a href="http://www.opensource.org/licenses/bsd-license.php" rel="external" class="external">BSD license</a></li> <li><a href="http://code.google.com/p/inspekt/downloads/list" rel="external" class="external">Download Inspekt</a></li> <li><a href="http://framework.zend.com/" rel="external" class="external">Zend Framework</a></li> <li><a href="http://inspekt.googlecode.com/svn/" rel="external" class="external">Inspekt svn</a></li> </ul> </li> <li><a href="http://www.php.net/manual/en/language.variables.predefined.php#language.variables.superglobals" rel="external" class="phpnet">PHP documentation: superglobals</a></li> <li>Blog article "<a href="http://www.sanisoft.com/blog/2007/10/15/inspekt-put-a-firewall-in-your-php-applications/" rel="external" class="external">Inspekt - put a firewall in your PHP applications</a>" by Dr. Tarique Sani</li> <li><a href="http://coppermine-gallery.net/forum/index.php?topic=47952.0" rel="external" class="external">Coppermine board: Inspekt introduction progress</a> (access restricted to dev team members)</li> <li><a href="http://coppermine-gallery.net/forum/index.php?topic=47980.0" rel="external" class="external">Coppermine board: Getting started with Inspekt for CPG</a> (access restricted to <a href="credits.htm#developers">dev team members</a>)</li> </ul> <div id="doc_footer"> <div class="doc_info_wrapper"> <span id="doc_last_changed">$LastChangedDate: 2011-01-02 20:44:22 +0100 (So, 02 Jan 2011) $</span> <span id="doc_revision">$Revision: 8154 $</span> </div> </div> </body> </html>