CGI::Application::Plugin::CAPTCHA (3pm)

Version 0.04

    # In your CGI::Application-based web application module. . .
    use CGI::Application::Plugin::CAPTCHA;

    sub setup
    {
        my $self = shift;

        $self->run_modes([ qw/
            create
            # Your other run modes go here
        /]);

        $self->captcha_config(
            IMAGE_OPTIONS    => {
                width    => 150,
                height   => 40,
                lines    => 10,
                font     => "/Library/Fonts/Arial",
                ptsize   => 18,
                bgcolor  => "#FFFF00",
            },
            CREATE_OPTIONS   => [ 'ttf', 'rect' ],
            PARTICLE_OPTIONS => [ 300 ],
        );
    }

    # Create a run mode that calls the CAPTCHA creation method...
    sub create
    {
        my $self = shift;
        return $self->captcha_create;
    }

    # In a template far, far away. . .
    <img src="/delight/Ident/create"> (to generate a CAPTCHA image)

    # Back in your application, to verify the CAPTCHA...
    sub some_other_runmode
    {
        my $self    = shift;
        my $request = $self->query;

        return unless $self->captcha_verify($request->cookie("hash"), $request->param("verify"));
    }

\*(C`CGI::Application::Plugin::CAPTCHA\*(C' allows programmers to easily add and verify CAPTCHAs in their CGI::Application-derived web applications.

A \s-1CAPTCHA\s0 (or Completely Automated Public Turing Test to Tell Computers and Humans Apart) is an image with a random string of characters. A user must successfully enter the random string in order to submit a form. This is a simple (yet annoying) procedure for humans to complete, but one that is significantly more difficult for a form-stuffing script to complete without having to integrate some sort of \s-1OCR\s0.

CAPTCHAs are not a perfect solution. Any skilled, diligent cracker will eventually be able to bypass a \s-1CAPTCHA\s0, but it should be able to shut down your average script-kiddie.

\*(C`CGI::Application::Plugin::CAPTCHA\*(C' is a wrapper for GD::SecurityImage. It makes it more convenient to access GD::SecurityImage functionality, and gives a more CGI::Application-like way of doing it.

When a \s-1CAPTCHA\s0 is created with this module, raw image data is transmitted from your web application to the client browser. A cookie containing a checksum is also transmitted with the image. When the client submits their form for processing (along with their verification of the random string), \*(C`captcha_verify()\*(C' generates a checksum of the verification string the user entered. If the newly generated checksum matches the checksum found in the cookie, we trust that the \s-1CAPTCHA\s0 has been successfully entered, and we allow the user to continue processing their form.

The checksum is generated by taking the string in question, and joining it with a \s-1SECRET\s0. We then generate an \s-1SHA1\s0 hex digest of the resulting string. The end user will not be able to generate their own checksums to bypass the \s-1CAPTCHA\s0 check, because they do not know the value of our \s-1SECRET\s0. This means it is important to choose a good value for your \s-1SECRET\s0.

An easy way to generate a relatively good secret is to run the following perl snippet:

perl -MDigest::SHA=sha1_base64 -le 'print sha1_base64($$,time(),rand(9999))'

The author recognizes that the transmission of a cookie with the \s-1CAPTCHA\s0 image may not be a popular decision, and welcomes any patches from those who can provide an equally easy-to-implement solution.

\fIcaptcha_config()\fP

This method is used to customize how new \s-1CAPTCHA\s0 images will be created. Values specified here are passed along to the appropriate functions in GD::SecurityImage when a new \s-1CAPTCHA\s0 is created.

It is recommended that you call \*(C`captcha_config()\*(C' in the \*(C`cgiapp_init()\*(C' method of your CGI::Application base class, and in the \*(C`setup()\*(C' method of any derived applications.

The following parameters are currently accepted:

\s-1IMAGE_OPTIONS\s0

This specifies what options will be passed to the constructor of GD::SecurityImage. Please see the documentation for GD::SecurityImage for more information.

\s-1CREATE_OPTIONS\s0

This specifies what options will be passed to the \*(C`create()\*(C' method of GD::SecurityImage. Please see the documentation for GD::SecurityImage for more information.

\s-1PARTICLE_OPTIONS\s0

This specifies what options will be passed to the \*(C`particle()\*(C' method of GD::SecurityImage. Please see the documentation for GD::SecurityImage for more information.

\s-1SECRET\s0

This specifies the secret that will be used when generating the checksum hash.

\fIcaptcha_create()\fP

Creates the \s-1CAPTCHA\s0 image, and return a cookie with the encrypted hash of the random string. Takes no arguments.

The cookie created in this method is named \*(C`hash\*(C', and contains only the encrypted hash. Future versions of this module will allow you to specify cookie options in greater detail.

\fIcaptcha_verify()\fP

Verifies that the value entered by the user matches what was in the \s-1CAPTCHA\s0 image. Argument 1 is the encrypted hash from the cookie sent by \*(C`captcha_create()\*(C', and argument 2 is the value the user entered to verify the \s-1CAPTCHA\s0 image. Returns true if the \s-1CAPTCHA\s0 was successfully verified, else returns false.

Jason A. Crome, \*(C`<[email protected]>\*(C'

• Allow \*(C`captcha_config()\*(C' to take cookie configuration arguments.

• Allow the plugin to actually create a run mode in your CGI::Application-based webapp without the developer having to manually create one.

Please report any bugs or feature requests to \*(C`[email protected]\*(C', or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-CAPTCHA <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-CAPTCHA>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

Patches, questions, and feedback are welcome.

A big thanks to Cees Hek for providing a great module for me to borrow code from (CGI::Application::Plugin::Session), to Michael Peters and Tony Fraser for all of their valuable input, and to the rest who contributed ideas and criticisms on the CGI::Application mailing list.

Additional thanks to chorny and Cees for the various bug fixes and patches they have submitted.

CGI::Application GD::SecurityImage Wikipedia entry for \s-1CAPTCHA\s0 - <http://en.wikipedia.org/wiki/Captcha>

Copyright 2005-2011 Jason A. Crome, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.