Generating One-Time URLs with PHP

by Daniel Solin
12/05/2002

Imagine that you're selling a digital product online. Maybe you've written an article or a book and want to sell it on your site as a PDF. There are many ways one could do this, but one of the more convenient is to provide the user with a unique URL that only will work a limited number of times. This URL could, for example, be presented to the user (your client) on the last page of an orderflow, after payment has been made. We will look at code to generate a unique URL that will work a single time.

Creating the URL

The script generate_url.php will generate our URLs. It uses PHP's md5() and uniqid() functions to create a unique, long and complicated token which will act as the key to the file to protect. Tokens are 32 random characters long, so to figure this out by mental arithmetic would be impossible. The listing below shows you the implementation of generate_url.php.

<?
/*
* generate_url.php
*
* Script for generating URLs that can be accessed one single time.
*
*/

/* Generate a unique token: */
$token = md5(uniqid(rand(),1));

/* This file is used for storing tokens. One token per line. */
$file = "/tmp/urls.txt";
if( !($fd = fopen($file,"a")) )
        die("Could not open $file!");

if( !(flock($fd,LOCK_EX)) )
        die("Could not aquire exclusive lock on $file!");

if( !(fwrite($fd,$token."\n")) )
        die("Could not write to $file!");

if( !(flock($fd,LOCK_UN)) )
        die("Could not release lock on $file!");

if( !(fclose($fd)) )
        die("Could not close file pointer for $file!");

/* Parse out the current working directory for this script. */
$cwd = substr($_SERVER['PHP_SELF'],0,strrpos($_SERVER['PHP_SELF'],"/"));

/* Report the one-time URL to the user: */
print "Use this URL to download the secret file:<br><br>\n";
print "<a href='http://".$_SERVER['HTTP_HOST']. 
      "$cwd/get_file.php?q=$token'>\n";
print "http://".$_SERVER['HTTP_HOST']."/get_file.php?q=$token</a>\n";

?>

In short terms, md5() calculates a 32-character long hexadecimal number by using the RSA Data Security, Inc. MD5 Message-Digest Algorithm out of the unique string generated by uniqid(). Note that we also feed uniqid() with a random value. You see, uniqid() generates a unique id based on the current time in microseconds. Although small, there's always a possibility that the script is executed two or more times simultaneously, which could result in the same id being generated more than once. By feeding uniqid() with a random value generated by rand(), we push the risk of not getting a really unique id closer to zero. Or, as stated in the PHP reference documentation, this generates a token "that is extremely difficult to predict". If you need more documentation on md5() and uniqid(), please consult the PHP reference documentation at http://www.php.net/manual/en/function.md5.php and http://www.php.net/manual/en/function.uniqid.php.

After generating the unique id, we open the file /tmp/urls.txt for writing. This file is used to store the unique tokens, one per line. When writing to this file, it's very important the we do real file-locking to prevent two processes writing the file at the same time. We do this by using PHP's flock() function. See http://www.php.net/manual/en/function.flock.php for more information about file-locking with PHP.

Finally, on the last three lines, the newly generated URL is presented to the client. It should show something like Figure 1.

Figure 1 -- A new and unique id is generated.

Sending Out the Secret File

As you saw in the previous section, there's reference to a file called get_file.php. This script takes care of the verification of a generated token, and, if the token is valid, sends out the secret file to the user. This file also deletes a token from /tmp/urls.txt after it has been used. See the listing below.

<?
/*
* get_file.php
*
* Script for validating a request through a secret token, passing a file
* to the user, and ensuring the token can not be used again.
*
*/

/* Retrive the given token: */
$token = $_GET['q'];

if( strlen($token)<32 )
{
        die("Invalid token!");
}

/* Define the secret file: */
$secretfile = "/tmp/secret_file.txt";

/* This variable is used to determine if the token is valid or not: */
$valid = 0;

/* Define what file holds the ids. */
$file = "/tmp/urls.txt";

/* Read the whole token-file into the variable $lines: */
$lines = file($file);

/* Truncate the token-file, and open it for writing: */
if( !($fd = fopen("/tmp/urls.txt","w")) )
        die("Could not open $file for writing!");

/* Aquire exclusive lock on $file. */
if( !(flock($fd,LOCK_EX)) )
        die("Could not equire exclusive lock on $file!");

/* Loop through all tokens in the token-file: */
for( $i = 0; $lines[$i]; $i++ )
{
        /* Is the current token the same as the one defined in $token? */
        if( $token == rtrim($lines[$i]) )
        {
                $valid = 1;
        }
        /* The code below will only get executed if $token does NOT match the
           current token in the token file. The result of this will be that
           a valid token will not be written to the token file, and will
           therefore only be valid once. */
        else
        {
                fwrite($fd,$lines[$i]);
        }
}

/* We're done writing to $file, so it's safe release the lock. */
if( !(flock($fd,LOCK_UN)) )
        die("Could not release lock on $file!");

/* Save and close the token file: */
if( !(fclose($fd)) )
        die("Could not close file pointer for $file!");

/* If there was a valid token in $token, output the secret file: */
if( $valid )
{
        readfile($secretfile);
}
else
{
        print "Invalid URL!";
}

?>

This script requires a token to be passed to it via the GET method. If a valid token is not provided, execution is terminated directly. This is a very important security issue. What would happen if an empty token was sent to the script and /tmp/urls.txt had an empty line on the end? Again, note the use of flock() to accomplish file-locking. This is, as in generate_url.php, an important feature for securing the file-handling.

Every line in urls.txt is then compared to the token that was sent to the script. If the token is actually present in urls.txt, the script marks the request as valid by setting $valid to 1. If the request is not valid, $valid will keep the value 0, and the secret file will not get passed to the user. Also note that all tokens that do not match the request are written to urls.txt again, but tokens that do match the request are skipped and, by that, removed from urls.txt .

Place get_file.php and generate_url.php on your Web server and click on the link shown in Figure 2. Depending on what is in your /tmp/secret_file.txt, you should now see something like Figure 2.

Figure 2 -- the super-secret contents of the super-secret file

As you see, get_file.php approved the request and presented us with the contents of /tmp/secret_file.txt. However, if you now try to reload the page, get_file.php will block the request. See Figure 3.

Figure 3 -- secret files without secret keys

Viola. Mission accomplished.

Summary

This article has presented a quick tip of how you could generate URLs that only can be used one time. It should be said, however, that for a real implementation of this function in a business environment, there are a few additional considerations to take. When the number of active keys grows past a few hundred, is it a good idea to read the whole file directly into memory? Is it wise even to store them in a plain-text file in the first place? Maybe a MySQL database would be a better choice? Additionally, consider the possibility of getting tokens "hijacked" directly from the urls.txt file. For getting this 100 percent secure, you either need to protect the file by setting very restrictive permission on it, only allowing the user executing your PHP scripts to read it. Or, you can simply dump the plain-text solution, and convert to a SQL-database instead.

The code in generate_url.php, of course has to be protected, too. The easiest way of doing that is probably to include it in the "thank-you-for-ordering-page" of your orderflow and make this file accessible only for clients coming from the secure-payment-complete-page. The core concept, though, will probably work very well in any production environment.

Daniel Solin is a freelance writer and Linux consultant whose specialty is GUI programming. His first book, SAMS Teach Yourself Qt Programming in 24 hours, was published in May, 2000.

---

Return to the PHP DevCenter.