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

1CGI::Application::PlugiUns:e:rCACPoTnCtHrAi(b3u)ted PerlCGDIo:c:uAmpepnltiactaitoinon::Plugin::CAPTCHA(3)
2
3
4

NAME

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

VERSION

10       Version 0.01
11

SYNOPSIS

13           # In your CGI::Application-based web application module. . .
14           use CGI::Application::Plugin::CAPTCHA;
15
16           sub setup
17           {
18               my $self = shift;
19
20               $self->run_modes([ qw/
21                   create
22                   # Your other run modes go here
23               /]);
24
25               $self->captcha_config(
26                   IMAGE_OPTIONS    => {
27                       width    => 150,
28                       height   => 40,
29                       lines    => 10,
30                       font     => "/Library/Fonts/Arial",
31                       ptsize   => 18,
32                       bgcolor  => "#FFFF00",
33                   },
34                   CREATE_OPTIONS   => [ 'ttf', 'rect' ],
35                   PARTICLE_OPTIONS => [ 300 ],
36               );
37           }
38
39           # Create a run mode that calls the CAPTCHA creation method...
40           sub create
41           {
42               my $self = shift;
43               return $self->captcha_create;
44           }
45
46           # In a template far, far away. . .
47           <img src="/delight/Ident/create"> (to generate a CAPTCHA image)
48
49           # Back in your application, to verify the CAPTCHA...
50           sub some_other_runmode
51           {
52               my $self    = shift;
53               my $request = $self->query;
54
55               return unless $self->captcha_verify($request->cookie("hash"), $request->param("verify"));
56           }
57

DESCRIPTION

59       "CGI::Application::Plugin::CAPTCHA" allows programmers to easily add
60       and verify CAPTCHAs in their CGI::Application-derived web applications.
61
62       A CAPTCHA (or Completely Automated Public Turing Test to Tell Computers
63       and Humans Apart) is an image with a random string of characters.  A
64       user must successfully enter the random string in order to submit a
65       form.  This is a simple (yet annoying) procedure for humans to
66       complete, but one that is significantly more difficult for a form-
67       stuffing script to complete without having to integrate some sort of
68       OCR.
69
70       CAPTCHAs are not a perfect solution.  Any skilled, diligent cracker
71       will eventually be able to bypass a CAPTCHA, but it should be able to
72       shut down your average script-kiddie.
73
74       "CGI::Application::Plugin::CAPTCHA" is a wrapper for GD::SecurityImage.
75       It makes it more convenient to access GD::SecurityImage functionality,
76       and gives a more CGI::Application-like way of doing it.
77
78       When a CAPTCHA is created with this module, raw image data is
79       transmitted from your web application to the client browser.  A cookie
80       containing an encrypted hash is also transmitted with the image.  When
81       the client submits their form for processing (along with their
82       verification of the random string), "captcha_verify()" encrypts the
83       verification string with the same salt used to encrypt the hash sent in
84       the cookie.  If the newly encrypted string matches the original
85       encrypted hash, we trust that the CAPTCHA has been successfully
86       entered, and we allow the user to continue processing their form.
87
88       The author recognizes that the transmission of a cookie with the
89       CAPTCHA image may not be a popular decision, and welcomes any patches
90       from those who can provide an equally easy-to-implement solution.
91

FUNCTIONS

93   captcha_config()
94       This method is used to customize how new CAPTCHA images will be
95       created.  Values specified here are passed along to the appropriate
96       functions in GD::SecurityImage when a new CAPTCHA is created.
97
98       It is recommended that you call "captcha_config()" in the
99       "cgiapp_init()" method of your CGI::Application base class, and in the
100       "setup()" method of any derived applications.
101
102       The following parameters are currently accepted:
103
104       IMAGE_OPTIONS
105
106       This specifies what options will be passed to the constructor of
107       GD::SecurityImage.  Please see the documentation for GD::SecurityImage
108       for more information.
109
110       CREATE_OPTIONS
111
112       This specifies what options will be passed to the "create()" method of
113       GD::SecurityImage.  Please see the documentation for GD::SecurityImage
114       for more information.
115
116       PARTICLE_OPTIONS
117
118       This specifies what options will be passed to the "particle()" method
119       of GD::SecurityImage.  Please see the documentation for
120       GD::SecurityImage for more information.
121
122   captcha_create()
123       Creates the CAPTCHA image, and return a cookie with the encrypted hash
124       of the random string.  Takes no arguments.
125
126       The cookie created in this method is named "hash", and contains only
127       the encrypted hash.  Future versions of this module will allow you to
128       specify cookie options in greater detail.
129
130   captcha_verify()
131       Verifies that the value entered by the user matches what was in the
132       CAPTCHA image.  Argument 1 is the encrypted hash from the cookie sent
133       by "captcha_create()", and argument 2 is the value the user entered to
134       verify the CAPTCHA image.  Returns true if the CAPTCHA was successfully
135       verified, else returns false.
136

AUTHOR

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

TODO

141       ·   Allow "captcha_config()" to take cookie configuration arguments.
142
143       ·   Allow the plugin to actually create a run mode in your
144           CGI::Application-based webapp without the developer having to
145           manually create one.
146

BUGS

148       Please report any bugs or feature requests to
149       "bug-cgi-application-plugin-captcha@rt.cpan.org", or through the web
150       interface at
151       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-CAPTCHA
152       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-
153       CAPTCHA>.  I will be notified, and then you'll automatically be
154       notified of progress on your bug as I make changes.
155

CONTRIBUTING

157       Patches, questions, and feedback are welcome.
158

ACKNOWLEDGEMENTS

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

COPYRIGHT & LICENSE

170       Copyright 2005 Jason A. Crome, all rights reserved.
171
172       This program is free software; you can redistribute it and/or modify it
173       under the same terms as Perl itself.
174
175
176
177perl v5.12.1                      2010-09-0C5GI::Application::Plugin::CAPTCHA(3)