A CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a type of challenge-response test that is used to determine whether the user is a human or a computer. It is often used to protect websites from spam and abuse by automated programs, also known as bots. CAPTCHAs typically consist of a distorted image of letters and numbers that a human user can read, but a computer program cannot. In order to pass the test, the user must type the letters and numbers correctly. CAPTCHAs are a common feature on many websites and are used to protect against a variety of threats, such as spam, phishing, and other types of online fraud.

Human Test captcha

Requirements:

Before you can use FirstProductions Human Test, be sure that your web site passes the minimum requirements:

  • Web Server: You must have web space to store web pages on a Unix server (script not tested on Windows NT). If not, consider getting web space from FirstProductions Web Hosting, our web hosting service. FirstProductions Web Hosting fully supports the requirements of this script.
  • CGI-BIN: You must be able to run custom CGI scripts on your web server, such as in a CGI-BIN. Note that most free web hosting services do not allow this (such as GeoCities, Tripod, and America Online).
  • Perl: Perl 5.004 or later must be installed on the web server. We suggest ActiveState Perl for Windows servers.
  • GD.pm: GD.pm 2.01 or later (with PNG support) to interface with GD Graphics Library
  • Digest::MD5: Used for encryption. The script can easily be recoded to use a different encryption algorithm to avoid using this library, should you so desire.
  • CGI.pm: Not required for the Human Test library, only for the example script.
  • File Permissions: For Unix servers, you will need the ability to set and change file permissions, either through FTP or Telnet. This is also known as CHMOD.
  • FTP Access: You will need to have FTP access to the web directories on your server. FrontPage access only is not sufficient.

Installation: Step 1: Uncompress the Package

First, you will need to uncompress the software package using WinZip or similar unzipping software. You should have a directory tree similar to this:

CGI (directory)
|__captcha.pl
|__captchatest.cgi
DATA (directory)
|__codes.txt
|__images (directory)
|__(various PNG files)

Installation: Step 2: Configure the Script

First open captchatest.cgi (the example script) in main CGI directory. Be sure that the first line of the script matches the path to Perl for your server. The path to Perl is usually similar to: /usr/bin/perl or /usr/local/bin/perl. Be sure not to remove the #! before the path to Perl. If you are unsure of the path to Perl, contact your server administrator.

Next, open captcha.pl in a text editor. This is the Human Test library used by the example script. You can also use this library in your own scripts for easy access to the Human Test functions (generateCode and checkCode). Here is a guide to configuring the options in the Settings section:

  • captcha_datafolder should not be accessible by the web. It will be used to store the image files used by the script, as well as the database. Do not include a trailing slash.
  • captcha_database should not need to be modified unless you move or rename the codes.txt file.
  • captcha_imagesfolder should not need to be modified unless you move or rename the images folder in the DATA directory.
  • captcha_outputfolder will be used to store the outputted images from the script, and should be accessible from the web. This setting is the path to the folder on your web server. Do not include a trailing slash.
  • captcha_webfolder is the URL to the folder specified in the captcha_outputfolder setting. Do not include a trailing slash.

Installation: Step 3: Upload Files to Server

After configuring the script, create a folder in your “cgi-bin” for the files in the CGI directory. Upload the files in the CGI directory to your new folder on your web server in ASCII mode. Make thecaptchatest.cgi file executable by CHMODing it as 755. Next, create the web-accessible folder you configured captcha_webfolder, and give it appropriate permissions so the script will be able to write files to it. Then, create the captcha_datafolder you specified in the configuration section outside of your web-accessible folders. Give it write permissions and upload the files in the DATA directory to this folder. Give the codes.txt database write permissions.

Installation: Step 4: Testing the Script

Now that you have uploaded the files, it is time to see if it worked. In a web browser, navigate to the URL of the example script (captchatest.cgi). If there is an error, see the troubleshooting section of the documentation. If it works, go on to the Usage section.

Usage

There are two functions that you can call in captcha.pl – generateCode and checkCode. The example script demonstrates how to use these two functions. Here is an explanation of the functions.

generateCode($length) will generate a random sequence of letters and numbers of the specified length. It will then encrypt the sequence using md5. The md5 crypt is what the function returns. The function also outputs a PNG image of the code sequence to the output folder. The md5 crypt is the filename without the .png suffix. The function will add the md5 crypt to the database in the data folder with a timestamp, and expire old codes from the database. If a crypt is not returned, then a file error occured.

checkCode($code,$crypt) will check a code against the md5 crypt and code database. There are several possible values that can be returned:

1 : Passed – the entered sequence is correct and the crypt is valid and was found in the database.
0 : Code not checked – a file error occured.
-1 : Failed: code expired – the code was found in the database but it was expired.
-2 : Failed: invalid code (not in database) – the code was not found in the database either because it expired, was already used, or it is invalid.
-3 : Failed: invalid code (code does not match crypt) – the entered sequence is incorrect and the crypt has been removed from the database.

For more information about using these functions, please refer to the example script included with this package.

Updated – we have just released an extensive tutorial showing how to integrate the Human Test library into an existing script. To read it, please go to the FormMail Example on our website.

Troubleshooting Guide

500 Internal Server Error
Possible causes of a 500 Internal Server Error:
• The path to Perl in line one of the captchatest.cgi file is incorrect. Contact your server administrator on consult your server’s documentation to find out your path to Perl.
• Files were not uploaded in ASCII mode. Transfer the files to your server again in ASCII mode.
• The permissions of captchatest.cgi were not set to executable. Set the permissions of captchatest.cgi to executable (CHMOD 755).
• The captcha.pl file was not found. If you renamed captcha.pl, name it back to captcha.pl.

404 File Not Found
Check the URL that you used to access captchatest.cgi and try again.

403 Forbidden
The permissions for captchatest.cgi were not set to executable (CHMOD 755).

Broken Image
If the example script displays a broken image, check the captcha_outputfolder and captcha_webfolder settings in the configuration section.

“Code not checked/generated (file error)”
Check the settings in the configuration section to be sure that they point to the correct folders, files, and paths.