| 1 |
NAME |
| 2 |
CGI::Application::Plugin::CAPTCHA - Easily create, use, and verify |
| 3 |
CAPTCHAs in CGI::Application-based web applications. |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 0.04 |
| 7 |
|
| 8 |
SYNOPSIS |
| 9 |
# In your CGI::Application-based web application module. . . |
| 10 |
use CGI::Application::Plugin::CAPTCHA; |
| 11 |
|
| 12 |
sub setup |
| 13 |
{ |
| 14 |
my $self = shift; |
| 15 |
|
| 16 |
$self->run_modes([ qw/ |
| 17 |
create |
| 18 |
# Your other run modes go here |
| 19 |
/]); |
| 20 |
|
| 21 |
$self->captcha_config( |
| 22 |
IMAGE_OPTIONS => { |
| 23 |
width => 150, |
| 24 |
height => 40, |
| 25 |
lines => 10, |
| 26 |
font => "/Library/Fonts/Arial", |
| 27 |
ptsize => 18, |
| 28 |
bgcolor => "#FFFF00", |
| 29 |
}, |
| 30 |
CREATE_OPTIONS => [ 'ttf', 'rect' ], |
| 31 |
PARTICLE_OPTIONS => [ 300 ], |
| 32 |
); |
| 33 |
} |
| 34 |
|
| 35 |
# Create a run mode that calls the CAPTCHA creation method... |
| 36 |
sub create |
| 37 |
{ |
| 38 |
my $self = shift; |
| 39 |
return $self->captcha_create; |
| 40 |
} |
| 41 |
|
| 42 |
# In a template far, far away. . . |
| 43 |
<img src="/delight/Ident/create"> (to generate a CAPTCHA image) |
| 44 |
|
| 45 |
# Back in your application, to verify the CAPTCHA... |
| 46 |
sub some_other_runmode |
| 47 |
{ |
| 48 |
my $self = shift; |
| 49 |
my $request = $self->query; |
| 50 |
|
| 51 |
return unless $self->captcha_verify($request->cookie("hash"), $request->param("verify")); |
| 52 |
} |
| 53 |
|
| 54 |
DESCRIPTION |
| 55 |
"CGI::Application::Plugin::CAPTCHA" allows programmers to easily add and |
| 56 |
verify CAPTCHAs in their CGI::Application-derived web applications. |
| 57 |
|
| 58 |
A CAPTCHA (or Completely Automated Public Turing Test to Tell Computers |
| 59 |
and Humans Apart) is an image with a random string of characters. A user |
| 60 |
must successfully enter the random string in order to submit a form. |
| 61 |
This is a simple (yet annoying) procedure for humans to complete, but |
| 62 |
one that is significantly more difficult for a form-stuffing script to |
| 63 |
complete without having to integrate some sort of OCR. |
| 64 |
|
| 65 |
CAPTCHAs are not a perfect solution. Any skilled, diligent cracker will |
| 66 |
eventually be able to bypass a CAPTCHA, but it should be able to shut |
| 67 |
down your average script-kiddie. |
| 68 |
|
| 69 |
"CGI::Application::Plugin::CAPTCHA" is a wrapper for GD::SecurityImage. |
| 70 |
It makes it more convenient to access GD::SecurityImage functionality, |
| 71 |
and gives a more CGI::Application-like way of doing it. |
| 72 |
|
| 73 |
When a CAPTCHA is created with this module, raw image data is |
| 74 |
transmitted from your web application to the client browser. A cookie |
| 75 |
containing a checksum is also transmitted with the image. When the |
| 76 |
client submits their form for processing (along with their verification |
| 77 |
of the random string), "captcha_verify()" generates a checksum of the |
| 78 |
verification string the user entered. If the newly generated checksum |
| 79 |
matches the checksum found in the cookie, we trust that the CAPTCHA has |
| 80 |
been successfully entered, and we allow the user to continue processing |
| 81 |
their form. |
| 82 |
|
| 83 |
The checksum is generated by taking the string in question, and joining |
| 84 |
it with a SECRET. We then generate an SHA1 hex digest of the resulting |
| 85 |
string. The end user will not be able to generate their own checksums to |
| 86 |
bypass the CAPTCHA check, because they do not know the value of our |
| 87 |
SECRET. This means it is important to choose a good value for your |
| 88 |
SECRET. |
| 89 |
|
| 90 |
An easy way to generate a relatively good secret is to run the following |
| 91 |
perl snippet: |
| 92 |
|
| 93 |
perl -MDigest::SHA1=sha1_base64 -le 'print sha1_base64($$,time(),rand(9999))' |
| 94 |
|
| 95 |
The author recognizes that the transmission of a cookie with the CAPTCHA |
| 96 |
image may not be a popular decision, and welcomes any patches from those |
| 97 |
who can provide an equally easy-to-implement solution. |
| 98 |
|
| 99 |
FUNCTIONS |
| 100 |
captcha_config() |
| 101 |
This method is used to customize how new CAPTCHA images will be created. |
| 102 |
Values specified here are passed along to the appropriate functions in |
| 103 |
GD::SecurityImage when a new CAPTCHA is created. |
| 104 |
|
| 105 |
It is recommended that you call "captcha_config()" in the |
| 106 |
"cgiapp_init()" method of your CGI::Application base class, and in the |
| 107 |
"setup()" method of any derived applications. |
| 108 |
|
| 109 |
The following parameters are currently accepted: |
| 110 |
|
| 111 |
IMAGE_OPTIONS |
| 112 |
This specifies what options will be passed to the constructor of |
| 113 |
GD::SecurityImage. Please see the documentation for GD::SecurityImage |
| 114 |
for more information. |
| 115 |
|
| 116 |
CREATE_OPTIONS |
| 117 |
This specifies what options will be passed to the "create()" method of |
| 118 |
GD::SecurityImage. Please see the documentation for GD::SecurityImage |
| 119 |
for more information. |
| 120 |
|
| 121 |
PARTICLE_OPTIONS |
| 122 |
This specifies what options will be passed to the "particle()" method of |
| 123 |
GD::SecurityImage. Please see the documentation for GD::SecurityImage |
| 124 |
for more information. |
| 125 |
|
| 126 |
SECRET |
| 127 |
This specifies the secret that will be used when generating the checksum |
| 128 |
hash. |
| 129 |
|
| 130 |
captcha_create() |
| 131 |
Creates the CAPTCHA image, and return a cookie with the encrypted hash |
| 132 |
of the random string. Takes no arguments. |
| 133 |
|
| 134 |
The cookie created in this method is named "hash", and contains only the |
| 135 |
encrypted hash. Future versions of this module will allow you to specify |
| 136 |
cookie options in greater detail. |
| 137 |
|
| 138 |
captcha_verify() |
| 139 |
Verifies that the value entered by the user matches what was in the |
| 140 |
CAPTCHA image. Argument 1 is the encrypted hash from the cookie sent by |
| 141 |
"captcha_create()", and argument 2 is the value the user entered to |
| 142 |
verify the CAPTCHA image. Returns true if the CAPTCHA was successfully |
| 143 |
verified, else returns false. |
| 144 |
|
| 145 |
AUTHOR |
| 146 |
Jason A. Crome, "<[email protected]>" |
| 147 |
|
| 148 |
TODO |
| 149 |
* Allow "captcha_config()" to take cookie configuration arguments. |
| 150 |
|
| 151 |
* Allow the plugin to actually create a run mode in your |
| 152 |
CGI::Application-based webapp without the developer having to |
| 153 |
manually create one. |
| 154 |
|
| 155 |
BUGS |
| 156 |
Please report any bugs or feature requests to |
| 157 |
"[email protected]", or through the web |
| 158 |
interface at |
| 159 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-C |
| 160 |
APTCHA>. I will be notified, and then you'll automatically be notified |
| 161 |
of progress on your bug as I make changes. |
| 162 |
|
| 163 |
CONTRIBUTING |
| 164 |
Patches, questions, and feedback are welcome. |
| 165 |
|
| 166 |
ACKNOWLEDGEMENTS |
| 167 |
A big thanks to Cees Hek for providing a great module for me to borrow |
| 168 |
code from (CGI::Application::Plugin::Session), to Michael Peters and |
| 169 |
Tony Fraser for all of their valuable input, and to the rest who |
| 170 |
contributed ideas and criticisms on the CGI::Application mailing list. |
| 171 |
|
| 172 |
Additional thanks to chorny and Cees for the various bug fixes and |
| 173 |
patches they have submitted. |
| 174 |
|
| 175 |
SEE ALSO |
| 176 |
CGI::Application GD::SecurityImage Wikipedia entry for CAPTCHA - |
| 177 |
<http://en.wikipedia.org/wiki/Captcha> |
| 178 |
|
| 179 |
COPYRIGHT & LICENSE |
| 180 |
Copyright 2005-2011 Jason A. Crome, all rights reserved. |
| 181 |
|
| 182 |
This program is free software; you can redistribute it and/or modify it |
| 183 |
under the same terms as Perl itself. |
| 184 |
|