CGI::Application::Plugin::CAPTCHA - Easily create, use, and verify CAPTCHAs in CGI::Application-based web

       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.

       Jason A. Crome, "<cromedome@cpan.org>"

       Please report any  bugs  or  feature  requests  to  "bug-cgi-application-plugin-captcha@rt.cpan.org",  or
       through                     the                    web                    interface                    at
       <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.

       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.

perl v5.36.0                                       2022-12-20             CGI::Application::Plugin::CAPTCHA(3pm)

       "CGI::Application::Plugin::CAPTCHA" allows programmers to easily add and verify CAPTCHAs in their
       CGI::Application-derived web applications.

       A CAPTCHA (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 OCR.

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

       "CGI::Application::Plugin::CAPTCHA" 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 CAPTCHA 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),
       "captcha_verify()" 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 CAPTCHA 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 SECRET. We then
       generate an SHA1 hex digest of the resulting string.  The end user will not be able to generate their own
       checksums to bypass the CAPTCHA check, because they do not know the value of our SECRET.  This means it
       is important to choose a good value for your SECRET.

       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 CAPTCHA image may not be a popular
       decision, and welcomes any patches from those who can provide an equally easy-to-implement solution.

captcha_config()
       This method is used to customize how new CAPTCHA images will be created.  Values specified here are
       passed along to the appropriate functions in GD::SecurityImage when a new CAPTCHA is created.

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

       The following parameters are currently accepted:

       IMAGE_OPTIONS

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

       CREATE_OPTIONS

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

       PARTICLE_OPTIONS

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

       SECRET

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

   captcha_create()
       Creates the CAPTCHA image, and return a cookie with the encrypted hash of the random string.  Takes no
       arguments.

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

   captcha_verify()
       Verifies that the value entered by the user matches what was in the CAPTCHA image.  Argument 1 is the
       encrypted hash from the cookie sent by "captcha_create()", and argument 2 is the value the user entered
       to verify the CAPTCHA image.  Returns true if the CAPTCHA was successfully verified, else returns false.

       CGI::Application::Plugin::CAPTCHA - Easily create, use, and verify CAPTCHAs in CGI::Application-based web
       applications.

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

           # 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"));
           }

       •   Allow "captcha_config()" 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.

       Version 0.04