Benjamin Franz

NAME

GD::SecurityImage::AC - A drop-in replacement for Authen::Captcha.

SYNOPSIS

  use GD::SecurityImage::AC;

  # create a new object
  my $captcha = Authen::Captcha->new();

  # set the data_folder. contains flatfile db to maintain state
  $captcha->data_folder('/some/folder');

  # set directory to hold publicly accessable images
  $captcha->output_folder('/some/http/folder');

  # Alternatively, any of the methods to set variables may also be
  # used directly in the constructor

  my $captcha = Authen::Captcha->new(
    data_folder   => '/some/folder',
    output_folder => '/some/http/folder',
    );

  # create a captcha. Image filename is "$md5sum.png"
  my $md5sum = $captcha->generate_code($number_of_characters);

  # check for a valid submitted captcha
  #   $code is the submitted letter combination guess from the user
  #   $md5sum is the submitted md5sum from the user (that we gave them)
  my $results = $captcha->check_code($code,$md5sum);
  # $results will be one of:
  #          1 : Passed
  #          0 : Code not checked (file error)
  #         -1 : Failed: code expired
  #         -2 : Failed: invalid code (not in database)
  #         -3 : Failed: invalid code (code does not match crypt)
  ##############

DESCRIPTION

This module is a drop-in GD::SecurityImage replacement for Authen::Captcha. Module is mostly compatible with Authen::Captcha. You can just replace

   use Authen::Captcha;

line in your programs with

   use GD::SecurityImage::AC;

to enable GD::SecurityImage interface. Alternatively, you can use

   use GD::SecurityImage backend => 'AC';

Regular GD::SecurityImage interface is supported with an extra method: gdsi. Also see the CAVEATS section for incompatibilities.

This module uses: GD::SecurityImage, Digest::MD5, File::Spec and Fcntl modules.

If you are writing a captcha handler from scratch, this module is not recommended. You must use GD::SecurityImage directly. This module can be used for older Authen::Captcha applications only. And features are (and will be) limited with Authen::Captcha capabilities.

Do not use this module if you have any doubt.

METHODS

See Authen::Captcha for the methods and usage.

gdsi

This method is used to set GD::SecurityImage parameters. Three methods are supported: new, create and particle. Parameter types and names are identical to GD::SecurityImage parameters:

   $captcha->gdsi(new      => {name => value},
                  create   => [param1, param2, ...],
                  particle => [param1, param2]);

new is a hashref while the other two are arrayrefs. See GD::SecurityImage for information about these parameters.

gdsi method must be called just after creating the object:

   my $captcha = Authen::Captcha->new;
   $captcha->gdsi(
      new => {
               width    => 350,
               height   => 100,
               lines    => 10,
               font     => "/absolute/path/to/your.ttf",
               scramble => 1,
               ptsize   => 24,
      },
      create   => [ttf => 'box', '#80C0F0', '#0F644B'],
      particle => [115, 250],
   );

If you don't use this method, the captcha image will be generated with default options.

gdsi returns the object itself. So, you can create your object like this:

   my $captcha = Authen::Captcha->new( ... )->gdsi( ... );

CAVEATS

  • width and height parameters are *not* character's width and height, but they define the image dimensions.

  • No outside images. Captchas are generated with the GD::SecurityImage interface, not with third party "letter" graphics (but you can use true type fonts, see gdsi method). As a side effect, captcha size is not (actually "can not be") determined automatically. so, you have to specify a width and height value at the beginning.

  • Setting images_folder has no effect.

  • No background images. Backgrounds are drawn with GD::SecurityImage styles.

  • You have to specify a TTF font, if you want to use another font (other than GD built-in GD::Font->Giant).

  • Setting debug has no effect. You can still set debug, but it is not used inside this module.

  • The code is compatible with taint, but only so long as your data_folder and output_folder paths are not tainted. This is deliberate. If your data_folder or output_folder paths are tainted, you are probably doing something wrong and definitely doing something that bears close examination.

CHANGES

1.11 2008.05.02 - Maintenance taken over by Benjamin Franz. Taint compatibility fixed and documented. Locking fixed. Example of CGI usage added (see examples/ folder). Artistic License file added. POD split into .pod file. Removed pointless AUTOLOAD subs. Add build test for taint. Removed use of 'base' module.

1.10 2006.02.19 => First release after separation from GD::SecurityImage distribution. => Fixed a bug in setting attributes in new() and AUTOLOAD(). => (Hopefully) fixed a bug related to unlink()ing images. Reported by GribUser.

SEE ALSO

GD::SecurityImage, Authen::Captcha.

AUTHOR

Burak Gürsoy, <burak@cpan.org>, Benjamin Franz <snowhare@cpan.org>

COPYRIGHT

Copyright 2005-2006 Burak Gürsoy, 2007 Benjamin Franz. All rights reserved.

Some portions of this module adapted from Authen::Captcha. Authen::Captcha Copyright 2003 by First Productions, Inc. & Seth Jackson.

LICENSE

This library is provided "AS IS" without warranty of any kind.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 179:

Non-ASCII character seen before =encoding in 'Gürsoy,'. Assuming ISO8859-1




Hosting generously
sponsored by Bytemark