Debian Codegraph @

README

raw ◀ ▶
1 Debian patch touch this file
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::SHA=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