Captcher

© 2006 Gecko Tribe, LLC
Captcher Homepage

Captcher is a PHP script that generates and verifies captchas. Capiche? Captchas are images designed to prevent automated scripts from submitting web forms, and are used to prevent spamming via email forms and online forums, and other such problems.

Requirements

• PHP with GD support for outputting GIFs (any reasonably up to date PHP installation)
• mySQL
• Support for Perl or PHP cron jobs recommended -- otherwise you'll need to run the cleanup script (which cleans unsolved captchas out of the database) manually on a regular basis or have a regularly visited webpage trigger it

Donations

Captcher is free, but the food that the author eats is not! If you use it, please consider making a donation. Use this form to donate via PayPal or by credit card:

License

Captcher may be downloaded and freely used for any legal purpose that is not forbidden by the terms in the license document. However, it is not "GPL" software. It may not be redistributed whether for free or not except as specified in the license. Refer to the license for more details.

Installation

1. Get some GD fonts. Use only fonts with a good set of uppercase letters--Captcher displays only uppercase letters. I use the "anonymous", "automatic" and "borringlesson" fonts from Widgnet.
2. Decide where on your server to install the fonts and scripts (other than captcher.php--it should go in a different location) and create the directory if necessary. I recommend putting everything except captcher.php outside of your web directory if possible, though some PHP installations will generate error messages if you do.
3. Enter the path to the directory chosen the previous step in the configuration section at the top of captcher.php. Be sure not to end the path with a "/" -- just enter everything up to the directory name.
4. Create a subdirectory named "gdfonts" inside the directory you chose and upload the fonts to that subdirectory.
5. If you are using different fonts from the ones named in step 1, enter their names (the name of the file without the ".gdf") in the "$fonts" array in the configuration section at the top of captcher.php.
6. Create a mySQL database (if you don't already have one), and then execute the contents of captcher.sql to create a table for Captcher.
7. Decide whether you want to use the Perl (.pl) or PHP version of captcher-clean to periodically delete old entries from the database. If you can run cron jobs on your server, captcher-clean.pl may be easier to set up. If not, captcher-clean.php may be easier to set up.
8. Enter the database and table names in the configuration sections of captcher-utils.php and either captcher-clean.pl or captcher-clean.php (whichever you decided to use). In captcher-utils.php and captcher-clean.php, enter them as "database-name.table-name" (ie. the database and table names separated by a dot). In captcher-clean.pl, the database and table names are entered separately.
9. Enter the path to a PHP script that opens a mySQL connection in the configuration section of captcher-utils.php. If you don't already have such a script, use captcher-mysql.php (enter your username and password in that file).
10. Enter your database username and password in captcher-clean.pl or captcher-clean.php (whichever you decided to use).
11. Upload captcher-utils.php, captcher-clean.pl or captcher-clean.php, and captcher-mysql (if you're going to use it) to the directory created in step 2.
12. Upload captcher.php to a web-accessible location on your server (I put it in my "img" directory, since it's going to output images).
13. If using captcher-clean.pl, make it executable by setting the access permissions to 755 (for a Linux/UNIX/BSD system) or whatever is necessary for your server's operating system. Ask your web host if you need help doing that.
14. If you can run cron jobs, set up a cron job to run captcher-clean.pl (you did take my advice and choose captcher-clean.pl, right?)--once an hour if possible. Ask your web host if you need help doing that.
15. If you can't run cron jobs, pick a PHP webpage on your site that's accessed regularly, but not too regularly (about once an hour is great, but it's not terribly critical if it's more or less often). Add the following code (adjusting the path as necessary) to the end of that file (you did take my advice and choose captcher-clean.php, right?):
    <?php include_once '/home/yourusername/captcher/captcher-clean.php'; ?>

Congratulations! Unless you or I have goofed up, you've finished the hard part!

Use

An example of how to use Captcher can be found in sample-captcher.php. The required operations are as follows:

In the form:

1. Load captcher-utils.php (use PHP's "require_once").
2. Create a key (MakeCaptchaKey) and store it with some captcha text in the database (StoreCaptcha or MakeCaptcha and StoreCaptcha).
3. Output a hidden field in your form contaning the key.
4. Output the captcha image (by passing the key to captcha.php).
5. Prompt the user to type the colored letters from the image.

In the script that processes the form:

1. Load captcher-utils.php.
2. Check whether the captcha text was entered correctly (CheckCaptcha).
3. If so, proceed with form processing.
4. Otherwise, display an error message.

Points of note from sample-captcher.php:

• $utilpath must be a local file path, not a URL.
• $captcherURL must be a URL, not a local file path.
• If the form you are using Captcher to protect is submitted with the GET method instead of POST, change $_POST to $_GET.
• The line "if (CheckCaptcha($_POST['key'],$_POST['entered'])) {" checks whether the user entered the correct captcha text. If it matches, the captcha is automatically deleted from the database so that it cannot be reused.
• The line "$newKey=MakeCaptchaKey();" generates a 32 character key, but does not store it in the database.
• The line "StoreCaptcha($newKey);" automatically generates the captcha text and stores it and the key in the database. There is no relationship between the key and the text, so no cryptographic exploit could determine the text from the key.
• The line '<input type="hidden" name="key" value="<?php echo $newKey; ?>" />' creates a hidden field in the form with the key.
• The line '<img src="<?php echo $captcherURL; ?>?key=<?php echo $newKey; ?>" style="margin-top:8px;" />' displays an HTML IMG tag which will display the captcha image.

Optional Configuration in captcher.php

• If you want to specify a fixed number of random letters to put in the background of the image, enter that in the "$randomletters" setting. To allow Captcher to decide the number of letters, leave it as "0".
• $textcolors specifies the colors that are used for the captcha letters. You may alter, reduce, or add to them if you wish.
• $backgroundcolors specifies the colors that are used for the letters in the background. You may alter, reduce, or add to them if you wish.

Function Reference

The following functions are defined in captcher-utils.php:

• MakeCaptcha($len=6)
  Generates and returns a random string of uppercase letters. The default length is 6 (yielding 308,915,776 possible captchas):
  $captcha=MakeCaptcha();
  You may specify a different length by calling the function like this:
  $captcha=MakeCaptcha(5);
   
• MakeCaptchaKey()
  Generates and returns a 32 character string to be used as a database key to identify a particular captcha:
  $key=MakeCaptchaKey();
   
• StoreCaptcha($key, $text='')
  Stores a captcha and its associated key in the database. If no captcha ($text) is specified, calls MakeCaptcha to generate one. Returns the captcha text (whether generated by this function or not).
  StoreCaptcha($key);
   
• CheckCaptcha($key, $entered, $delete=1)
  Checks whether the captcha text entered by the user ($entered) matches the text stored in the database associated with the key ($key). Returns 1 if they match and 0 if not. The comparison is not case sensitive. If $deleted = 1 (the default), deletes the captcha from the database if it matches.
  CheckCaptcha($_POST['key'], $_POST['captcha']);
   
• GetCaptchaText($key)
  Retrieves and returns the captcha text associated with the specified key.
  $captcha=GetCaptchaText($_GET['key']);