PHP Captcha 1.0

June 4th, 2007
Copyright (C) 2007 Kerem Erkan <kerem@keremerkan.net>
http://www.keremerkan.net/
http://blog.keremerkan.net/

This document explains the installation, requirements and usage of PHP
Captcha. It consists of the following sections:

  1. Information
  2. Installation
  3. Usage

Please read it thoroughly as you will need to make some configuration.


=== INFORMATION ==========================================================

PHP Captcha is a powerful CAPTCHA generator which can be used to help
eliminate bot actions in your site scripts.

The difference of PHP Captcha from other scripts written in PHP is, it is
written to utilize ImageMagick functions through the wonderful MagickWand
API to create CAPTCHA images that are hard enough for bots to crack, while
more readable by humans than the others. Also, PHP Captcha has a lot of
customization options.

Be aware that, for the casual user that visits your site, a CAPTCHA image
is an "enter what you see" image. That is, if the users see the
characters "ABCD" in an image, their first action will be entering "ABCD".
They will probably not read the instructions about the image in your page
which may say "enter minimum X characters from the image" or "enter the
characters in the direction the arrow in the image points to", etc.

This is what Aleksey Kolupaev of OCR Research Team told me.

The default configuration of PHP Captcha is based on the principle above,
but you are welcome to try different configuration options if your user
base has an "above average" awareness.

PHP Captcha is licensed under the GNU GPL. For full terms see the file
LICENSE.

I distribute Verdana and Verdana Bold with PHP Captcha. If you know that
it is illegal to distribute this font family (it seems to be free),
please contact me, so I will replace them with some other font family.

I also distribute Pointers, a font by Russ Rowlett, which is used to
create the arrows in the CAPTCHA image. The documentation for Pointers
is included in pointers.tar.bz2 file under the fonts folder.

If you use PHP Captcha and find it useful, please contact me and tell me
the page you use it in. I would like to reference your site from my blog.

Also you are very welcome to make a small donation if you think that PHP
Captcha has saved you from some hassle. You can find my PayPal donation
button on my blog site: http://blog.keremerkan.net/


=== INSTALLATION =========================================================

PHP Captcha consists of 4 parts.

  1. image.php which will render the CAPTCHA image.
  2. functions.php which includes various functions needed for PHP Captcha
  3. config.php which includes variables to control the rendered image.
  4. fonts directory which includes the fonts needed for CAPTCHA text.

To get PHP Captcha working correctly, you will need 2 essential
applications installed on your system. These are:

  1. ImageMagick (http://www.imagemagick.org)

  ImageMagick is the essential application that handles all drawing
  functions. You can install it from source, or from your distribution
  packages. A simple install should be like:

  # ./configure --prefix=/usr/local/imagemagick --with-modules
  # make
  #make install

  Check the ImageMagick site for thorough installation instructions.

  2. MagickWand PHP API (http://www.magickwand.org)

  MagickWand is the API between PHP and ImageMagick that enables their
  communication. I don't know any Linux distributions that have this
  application as a package, so you will have to install it from source.

  At the time of writing this document, official MagickWand installation
  instructions were not very helpful in installing MagickWand as a PHP
  module, so I wrote some instructions below. Do not try to recompile your
  PHP installation like they state in their site, it is not needed.

  Download the latest API source, untar and ungzip it to a directory.
  After that go to that directory and execute:

  # phpize

  phpize will help you configure MagickWand for your PHP environment.
  After it finishes its work, you can configure and install MagickWand like
  this:

  # ./configure --with-magickwand=/usr/local/imagemagick
  # make
  # make install

  Don't forget to point --with-magickwand option to your ImageMagick
  installation directory.

  After executing "make install", a module named "magickwand.so" will be
  installed in the extensions directory of PHP. You will have to activate
  this module in your php.ini. Write the below line to your php.ini

  extension=magickwand.so

  Restart your webserver and you should be ready to go.

  If your PHP installation cannot find magickwand.so, make sure that the
  "extension_dir" variable in php.ini points to the directory that
  magickwand.so resides in.

Now as you have installed these applications, check the config.php file
of PHP Captcha, and edit it if you need to. The default values should be
good for most people.


=== USAGE ================================================================

After untarring and ungzipping PHP Captcha to your webroot and installing
ImageMagick and MagickWand, you will be ready to use PHP Captcha.

To use it, simply call the image.php like you call an ordinary image
from your site. For example:

<img src="/phpcaptcha/image.php" alt="CAPTCHA Text"/>

image.php will display an image and also will set a session variable
named $_SESSION["captcha"]. This variable is protected from prying eyes
using md5 enryption, so if the bot somehow gets the contents of this
variable, it still needs to decrypt it to have the right answer (which
will be a real pain for it, so probably it will not bother trying this).
Be careful though, if you have set the "min_correct_characters" to an
acceptable value in config.php, the encryption will be disabled.

On the page to which your users will post the captcha answer, you need
to check the answer. To do this, use the "phpcaptcha_check_captcha"
function. To use this function, you will have to include the functions.php
of PHP Captcha in your script and post a variable named $_POST["captcha"]
to your page. "phpcaptcha_check_captcha" function only works if the
posted variable is $_POST["captcha"].

This function has 6 return values:

 0 : The user gave a correct answer
-1 : The user gave a wrong answer
-2 : The user gave an answer including non alphanumeric characters or too
     many characters. Possibly an attack trial.
-3 : The user posted an empty answer with no characters.
-4 : The CAPTCHA session variable is not set. After checking the answer,
     the function unsets the session variable $_SESSION["captcha"] so that
     retrying the same variable with different answers for a bruteforce
     attack does not work.
-5 : The CAPTCHA string has expired. If you have set an expiration time
     for the string using "expiration_time" variable in config.php and the
     user did not post the CAPTCHA string before expiration, even if the
     answer is true, the answer will not be accepted.

If this function returns 0, you can be sure that your users have entered a
correct answer, for all other return values, you will require your users
post a new CAPTCHA answer.

A simple check should be like this in your script:

<?php

@session_start();

require_once("/path/to/phpcaptcha/functions.php");

... Some code

$return = phpcaptcha_check_captcha();

if ( $return == 0 )
{
  ... the code that logs in your users.
}
else
{
  ... the code that requires your users to enter the CAPTCHA again.
}

... Some other code

?>

There is one variable in config.php that needs mentioning about here. It is
$text_direction, which can be externally set by you in your scripts. To
set this variable externally, include the functions.php in your script and
call the function "phpcaptcha_set_random_text_direction". An example:

<?php

@session_start();

require_once("/path/to/papcaptcha/functions.php");

phpcaptcha_set_random_text_direction();

?>

This function will set the $text_direction variable to "LR" or "RL"
randomly. If the value is "LR", your users will have to write the
characters they see in the image, "from left to right". If it is "RL",
they will have to write it "from right to left". This puts another layer
of protection to your scripts.

Be sure to randomize the text direction BEFORE calling the image in your
page to avoid nasty side effects.

If you randomize the text direction, you should better set the
"text_direction_pointer" variable to 1 in config.php to show the direction
to your users in the image instead of your page. If you set this variable
to 0, you will have to check the value of
$_SESSION["captcha_text_direction"] variable and tell the direction to your
users on your page.

Again I am saying, if you have set the "min_correct_characters" to an
acceptable value in config.php, "text_direction" and
"text_direction_pointer" variables will be disabled like the md5 encryption
of $_SESSION["captcha"], as I told before.

That's all. I hope you like PHP Captcha.
