1Captcha(3) User Contributed Perl Documentation Captcha(3)
2
6 Authen::Captcha - Perl extension for creating captcha's to verify the
7 human element in transactions.
8
10 use Authen::Captcha;
11 # create a new object
13 my $captcha = Authen::Captcha->new();
14 # set the data_folder. contains flatfile db to maintain state
16 $captcha->data_folder('/some/folder');
17 # set directory to hold publicly accessible images
19 $captcha->output_folder('/some/http/folder');
20 # Alternitively, any of the methods to set variables may also be
22 # used directly in the constructor
23 my $captcha = Authen::Captcha->new(
25 data_folder => '/some/folder',
26 output_folder => '/some/http/folder',
27 );
28 # create a captcha. Image filename is "$token.png"
30 my $token = $captcha->generate_code($number_of_characters);
31 # check for a valid submitted captcha
33 # $code is the submitted letter combination guess from the user
34 # $token is the submitted token from the user (that we gave them)
35 my $results = $captcha->check_code($code,$token);
36 # $results will be one of:
37 # 1 : Passed
38 # 0 : Code not checked (file error)
39 # -1 : Failed: code expired
40 # -2 : Failed: invalid code (not in database)
41 # -3 : Failed: invalid code (code does not match token)
42 ##############
43
45 The captcha produced by this module is rather weak compared to other
46 modules available. You are advised to update to GD::SecurityImage,
47 which provides API-compatible interface in GD::SecurityImage::AC
48 module.
49
51 Authen::Captcha provides an object oriented interface to captcha file
52 creations. Captcha stands for Completely Automated Public Turing test
53 to tell Computers and Humans Apart. A Captcha is a program that can
54 generate and grade tests that:
55 - most humans can pass.
57 - current computer programs can't pass
58 The most common form is an image file containing distorted text, which
60 humans are adept at reading, and computers (generally) do a poor job.
61 This module currently implements that method. We plan to add other
62 methods, such as distorted sound files, and plain text riddles.
63
65 GD (see http://search.cpan.org/~lds/GD-2.11/)
66 Digest::MD5 (standard perl module)
67 In most common situations, you'll also want to have:
69 A web server (untested on windows, but it should work)
71 cgi-bin or mod-perl access
72 Perl: Perl 5.00503 or later must be installed on the web server.
73 GD.pm (with PNG support)
74
76 Download the zipped tar file from:
77 http://search.cpan.org/search?dist=Authen-Captcha
79 Unzip the module as follows or use winzip:
81 tar -zxvf Authen-Captcha-1.xxx.tar.gz
83 The module can be installed using the standard Perl procedure:
85 perl Makefile.PL
87 make
88 make test
89 make install # you need to be root
90 Windows users without a working "make" can get nmake from:
92 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
94
96 MAIN METHODS
97 "$captcha = Authen::Captcha->new();"
98 This creates a new Captcha object. Optionally, you can pass in a
99 hash with configuration information. See the method descriptions
100 for more detail on what they mean.
101 data_folder => '/some/folder', # required
103 output_folder => '/some/http/folder', # required
104 expire => 300, # optional. default 300
105 width => 25, # optional. default 25
106 height => 35, # optional. default 35
107 images_folder => '/some/folder', # optional. default to lib dir
108 keep_failures => 0, # optional, defaults to 0(false)
109 debug => 0, # optional. default 0
110 "$token = $captcha->generate_code( $number_of_characters );"
112 Creates a captcha. Image filename is "$token.png"
113 It can also be called in array context to retrieve the string of
115 characters used to generate the captcha (the string the user is
116 expected to respond with). This is useful for debugging. ex.
117 "($token,$chars) = $captcha->generate_code( $number_of_characters
119 );"
120 "$results = $captcha->check_code($code,$token);"
122 check for a valid submitted captcha
123 $code is the submitted letter combination guess from the user
125 $token is the submitted token from the user (that we gave them)
127 If the $code and $token are correct, the image file and database
129 entry will be removed.
130 If the $token matches one in the database, and "keep_failures" is
132 false (the default), the image file and database entry will be
133 removed to avoid repeated attempts on the same captcha.
134 $results will be one of:
136 1 : Passed
138 0 : Code not checked (file error)
139 -1 : Failed: code expired
140 -2 : Failed: invalid code (not in database)
141 -3 : Failed: invalid code (code does not match token)
142 ACCESSOR METHODS
144 "$captcha->data_folder( '/some/folder' );"
145 Required. Sets the directory to hold the flatfile database that
146 will be used to store the current non-expired valid captcha tokens.
147 Must be writable by the process running the script (usually the web
148 server user, which is usually either "apache" or "http"), but
149 should not be accessible to the end user.
150 "$captcha->output_folder( '/some/folder' );"
152 Required. Sets the directory to hold the generated Captcha image
153 files. This is usually a web accessible directory so that the user
154 can view the images in here, but it doesn't have to be web
155 accessible (you could be attaching the images to an e-mail for some
156 verification, or some other Captcha implementation). Must be
157 writable by the process running the script (usually the web server
158 user, which is usually either "apache" or "http").
159 "$captcha->images_folder( '/some/folder' );"
161 Optional, and may greatly affect the results... use with caution.
162 Allows you to override the default character graphic png's and
163 backgrounds with your own set of graphics. These are used in the
164 generation of the final captcha image file. The defaults are held
165 in:
166 [lib install dir]/Authen/Captcha/images
167 "$captcha->expire( 300 );"
169 Optional. Sets the number of seconds this captcha will remain
170 valid. This means that the created captcha's will not remain valid
171 forever, just as long as you want them to be active. Set to an
172 appropriate value for your application. Defaults to 300.
173 "$captcha->width( 25 );"
175 Optional. Number of pixels high for the character graphics.
176 Defaults to 25.
177 "$captcha->height( 35 );"
179 Optional. Number of pixels wide for the character graphics.
180 Defaults to 35.
181 "$captcha->keep_failures( [0|1] );"
183 Optional. Defaults to zero. This option controls whether or not the
184 captcha will remain valid after a failed attempt. By default, we
185 only allow one attempt to solve it. This greatly reduces the
186 possibility that a bot could brute force a correct answer. Change
187 it at your own risk.
188 "$captcha->debug( [0|1|2] );"
190 Optional. Sets the debugging bit. 1 turns it on, 0 turns it off. 2
191 will print out verbose messages to STDERR.
192
194 sound file captcha: Incorporating distorted sound file creation.
195
197 The Captcha project:
198 http://www.captcha.net/
199 The origonal perl script this came from:
201 http://www.firstproductions.com/cgi/
202
204 Seth T. Jackson, <sjackson@purifieddata.net>
205 Josh I. Miller, <jmiller@purifieddata.net>
207 First Productions, Inc. created the cgi-script distributed under the
209 GPL which was used as the basis for this module. Much work has gone
210 into making this more robust, and suitable for other applications, but
211 much of the origonal code remains.
212 Fixes were reported and contributed by various people, see Changes file
214 for a complete list.
215
217 Copyright 2003, First Productions, Inc. (FIRSTPRODUCTIONS HUMAN TEST
218 1.0)
219 Copyright 2003 by Seth Jackson
221 Copyright 2012 by Paolo Rossi, Lubomir Rintel, Chris Dunlop, Gert
223 Schepens and Ernesto Hernández-Novich
224 This library is free software; you can redistribute it and/or modify it
226 under the terms of the GNU General Public License as published by the
227 Free Software Foundation; either version 2 of the License, or (at your
228 option) any later version. (see license.txt).
229 This program is distributed in the hope that it will be useful, but
231 WITHOUT ANY WARRANTY; without even the implied warranty of
232 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
233 General Public License for more details.
234 You should have received a copy of the GNU General Public License along
236 with this program; if not, write to the Free Software Foundation, Inc.,
237 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
238
240 Hey! The above document had some coding errors, which are explained
241 below:
242 Around line 764:
244 Non-ASCII character seen before =encoding in 'Hernández-Novich'.
245 Assuming UTF-8
246perl v5.38.0 2023-07-20 Captcha(3)