FirstProductions Human Test
FormMail Example

Script Outputs Form Tutorial

Use this tutorial if your CGI script outputs the form (if the script does not output the form, please use our Script Does Not Output Form Tutorial instead). Before continuing be sure to download the formmail.zip file, which contains the example scripts used in this tutorial. This tutorial will only use formmail1.cgi (original script) and formmail2.cgi (modified script to use Human Test).

Examining the Script

First take a look at formmail1.cgi. This is the original FormMail script that we want to integrate the Human Test library into. Please note that this script was created especially for this tutorial, and is not intended to be used in an actual setting. It may contain security holes that we are not aware of.

We also have an example of the original script and the script modified to use Human Test running on our server as a demonstration. These have been modified so they do not actually send mail.

The script first has a configuration section. Configure the script to work with your server.

Next, the script looks to see if you are submitting the form.

	if ($sendmail == 1){

The $sendmail variable is set when the form is submitted. If the form is not being submitted, then the script needs to display the form.

	&output_form;

The script does three things to submit the form.

	&get_fields;
	&send_mail;
	&output_sent;

First, it gets the input fields, then it sends the mail, then it outputs a page that says the mail has been sent.

Adding Human Test Library to the Script

To add the Human Test library to the script, first be sure that the library is configured and working on your server by using the test script included with the Human Test library. Next you need to tell the script that you want to use the Human Test library by inserting this line towards the beginning of the script (we placed it just after the use CGI; statement.

	require "captcha.pl";

This should point to the Human Test library installed on your server. If it is not in the same directory as the script, use the full or relative server path to the library.

Adding Human Test Library to Form Output

Our example script outputs the form in the output_form subroutine. Find this subroutine in the script. At the beginning of this subroutine, before it outputs the form, the script needs to generate the code.

	$crypt = &generateCode(8);

This function generates a code that is eight characters in length.

Next we need to output the crypt, an encrypted version of the code, which is outputted to a hidden form field. Add this line of code just below the hidden form field (named sendmail) already in the script.

	print "<input type=\"hidden\" name=\"crypt\" value=\"$crypt\">\n";

This hidden form field contains the encrypted version of the code ($crypt) needed to check the entered code.

Now we need to output the image. Add these lines of code to the form just before the line that contains the Submit button.

	print "<p>Security code: <img src=\"$captcha_webfolder/$crypt.png\" width=".($captcha_length*$captcha_width)." height=$captcha_height border=0><br>\n";
	print "Please enter the characters you see in the image: <input type=\"text\" name=\"code\" value=\"\"></p>\n";

The first line shows the security code. The image is located in the folder specified in the configuration section of the Human Test library ($captcha_webfolder), and the name of the image is the encrypted version of the code ($crypt) with the .png suffix. The width of the image is the number of characters ($captcha_length=8) multiplied by the width of each character ($captcha_width). The height of the image is the same as the height of each character ($captcha_height) as all of the characters are lined up in a row.

The second line contains an input box to enter the code.

Adding Human Test Library to Form Processing

Our example script processes the form in the get_fields subroutine. Find this subroutine in the script. At the end of this subroutine, after it checks the name, email, and comments, the script needs to check the code.

	$code = $q->param('code');
	$crypt = $q->param('crypt');

These two lines of code get the code variable and crypt variable from the form. $code contains the code entered by the user, and $cyrpt contains the encrypted version of the code passed to the script via the hidden form field. Now to actually check the code using the checkCode function.

	if ($code && $crypt){
		$result = &checkCode($code,$crypt);
		if ($result != 1){
			&error("Incorrect or expired security code! Please try the new code below.");
		}
	}
	else{
		&error("Security code is required! Please try the new code below.");
	}

What this code does is first checks to be sure the user entered a code. If not, the script outputs an error. Next the script runs the code and crypt through the checkCode function from the Human Test library. If the code and crypt are valid, the function returns a value of one. If the function returns zero or a negative value (different returned values are explained in the Human Test library documentation), then the code is either incorrect or expired, so the script outputs an error if the function does not return a value of one.

Conclusion

The Human Test library is now fully integrated into the example FormMail script. The final script is included in the zip file named formmail2.cgi. Please review the steps needed to integrate the Human Test library into an existing script that outputs the form. Then use this knowledge to integrate Human Test library into your own scripts. If you have any questions or need additional assistance, please use our Support Forums.