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.04
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 a checksum is also transmitted with the image.  When the
81       client submits their form for processing (along with their verification
82       of the random string), "captcha_verify()" generates a checksum of the
83       verification string the user entered.  If the newly generated checksum
84       matches the checksum found in the cookie, we trust that the CAPTCHA has
85       been successfully entered, and we allow the user to continue processing
86       their form.
87
88       The checksum is generated by taking the string in question, and joining
89       it with a SECRET. We then generate an SHA1 hex digest of the resulting
90       string.  The end user will not be able to generate their own checksums
91       to bypass the CAPTCHA check, because they do not know the value of our
92       SECRET.  This means it is important to choose a good value for your
93       SECRET.
94
95       An easy way to generate a relatively good secret is to run the
96       following perl snippet:
97
98         perl -MDigest::SHA1=sha1_base64 -le 'print sha1_base64($$,time(),rand(9999))'
99
100       The author recognizes that the transmission of a cookie with the
101       CAPTCHA image may not be a popular decision, and welcomes any patches
102       from those who can provide an equally easy-to-implement solution.
103

FUNCTIONS

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

AUTHOR

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

TODO

158       •   Allow "captcha_config()" to take cookie configuration arguments.
159
160       •   Allow the plugin to actually create a run mode in your
161           CGI::Application-based webapp without the developer having to
162           manually create one.
163

BUGS

165       Please report any bugs or feature requests to
166       "bug-cgi-application-plugin-captcha@rt.cpan.org", or through the web
167       interface at
168       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-CAPTCHA>.
169       I will be notified, and then you'll automatically be notified of
170       progress on your bug as I make changes.
171

CONTRIBUTING

173       Patches, questions, and feedback are welcome.
174

ACKNOWLEDGEMENTS

176       A big thanks to Cees Hek for providing a great module for me to borrow
177       code from (CGI::Application::Plugin::Session), to Michael Peters and
178       Tony Fraser for all of their valuable input, and to the rest who
179       contributed ideas and criticisms on the CGI::Application mailing list.
180
181       Additional thanks to chorny and Cees for the various bug fixes and
182       patches they have submitted.
183

COPYRIGHT & LICENSE

189       Copyright 2005-2011 Jason A. Crome, all rights reserved.
190
191       This program is free software; you can redistribute it and/or modify it
192       under the same terms as Perl itself.
193
194
195
196perl v5.36.0                      2022-07-2C2GI::Application::Plugin::CAPTCHA(3)