Category list

12.2 Filenames

It's fairly easy to construct a filename that refers to something other than what you intended. For example, say you have a $username variable that contains the name the user wants to be called, which the user has specified through a form field. Now let's say you want to store a welcome message for each user in the directory /usr/local/lib/ greetings , so that you can output the message any time the user logs into your application. The code to print the current user's greeting is:

<?php include("/usr/local/lib/greetings/$username") ?>

This seems harmless enough, but what if the user chose the username "../../../../etc/passwd" ? The code to include the greeting now includes /etc/passwd instead. Relative paths are a common trick used by hackers against unsuspecting scripts.

Another trap for the unwary programmer lies in the way that, by default, PHP can open remote files with the same functions that open local files. The fopen( ) function and anything that uses it (e.g., include( ) and require( ) ) can be passed an HTTP or FTP URL as a filename, and the document identified by the URL will be opened. Here's some exploitable code:

<?php
  chdir("/usr/local/lib/greetings");
  $fp = fopen($username, "r");
?>

If $username is set to "http://www.example.com/myfile" , a remote file is opened, not a local one.

The situation is even more dire if you let the user tell you which file to include( ) :

<?php
  $file = $_REQUEST['theme'];
  include($file);
?>

If the user passes a theme parameter of "http://www.example.com/badcode.inc" and your variables_order includes GET or POST, your PHP script will happily load and run the remote code. Never use parameters as filenames like this.

There are several solutions to the problem of checking filenames. You can disable remote file access, check filenames with realpath( ) and basename( ) , and use the open_basedir option to restrict filesystem access.

12.2.1 Check for Relative Paths

When you need to allow the user to specify a filename in your application, you can use a combination of the realpath( ) and basename( ) functions to ensure that the filename is what it ought to be. The realpath( ) function resolves special markers such as "." and "..". After a call to realpath( ) , the resulting path is a full path on which you can then use basename( ) . The basename( ) function returns just the filename portion of the path.

Going back to our welcome message scenario, here's an example of realpath( ) and basename( ) in action:

$filename = $_POST['username'];
$vetted = basename(realpath($filename));
if ($filename !== $vetted) {
  die("$filename is not a good username");
}

In this case, we've resolved $filename to its full path and then extracted just the filename. If this value doesn't match the original value of $filename , we've got a bad filename that we don't want to use.

Once you have the completely bare filename, you can reconstruct what the file path ought to be, based on where legal files should go, and add a file extension based on the actual contents of the file:

include("/usr/local/lib/greetings/$filename");

12.2.2 Restrict Filesystem Access to a Specific Directory

If your application must operate on the filesystem, you can set the open_basedir option to further secure the application by restricting access to a specific directory. If open_basedir is set in php.ini , PHP limits filesystem and I/O functions so that they can operate only within that directory or any of its subdirectories. For example:

open_basedir = /some/path

With this configuration in effect, the following function calls succeed:

unlink("/some/path/unwanted.exe");
include("/some/path/less/travelled.inc");

But these generate runtime errors:

$fp = fopen ("/some/other/file.exe", "r");
$dp = opendir("/some/path/../other/file.exe");

Of course, one web server can run many applications, and each application typically stores files in its own directory. You can configure open_basedir on a per-virtual host basis in your httpd.conf file like this:

<VirtualHost 1.2.3.4>
  ServerName domainA.com
  DocumentRoot /web/sites/domainA
  php_admin_value open_basedir /web/sites/domainA
</VirtualHost>

Similarly, you can configure it per directory or per URL in httpd.conf :

# by directory
<Directory /home/httpd/html/app1>
  php_admin_value open_basedir /home/httpd/html/app1
</Directory>

# by URL
<Location /app2>
  php_admin_value open_basedir /home/httpd/html/app2
</Location>

The open_basedir directory can be set only in the httpd.conf file, not in . htaccess files, and you must use php_admin_value to set it.