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 accessable 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 "$md5sum.png"
30 my $md5sum = $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 # $md5sum is the submitted md5sum from the user (that we gave them)
35 my $results = $captcha->check_code($code,$md5sum);
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 crypt)
42 ##############
43
45 Authen::Captcha provides an object oriented interface to captcha file
46 creations. Captcha stands for Completely Automated Public Turning test
47 to tell Computers and Humans Apart. A Captcha is a program that can
48 generate and grade tests that:
49 - most humans can pass.
51 - current computer programs can't pass
52 The most common form is an image file containing distorted text, which
54 humans are adept at reading, and computers (generally) do a poor job.
55 This module currently implements that method. We plan to add other
56 methods, such as distorted sound files, and plain text riddles.
57
59 GD (see http://search.cpan.org/~lds/GD-2.11/)
60 Digest::MD5 (standard perl module)
61 In most common situations, you'll also want to have:
63 A web server (untested on windows, but it should work)
65 cgi-bin or mod-perl access
66 Perl: Perl 5.00503 or later must be installed on the web server.
67 GD.pm (with PNG support)
68
70 Download the zipped tar file from:
71 http://search.cpan.org/search?dist=Authen-Captcha
73 Unzip the module as follows or use winzip:
75 tar -zxvf Authen-Captcha-1.xxx.tar.gz
77 The module can be installed using the standard Perl procedure:
79 perl Makefile.PL
81 make
82 make test
83 make install # you need to be root
84 Windows users without a working "make" can get nmake from:
86 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
88
90 MAIN METHODS
91 "$captcha = Authen::Captcha->new();"
92 This creates a new Captcha object. Optionally, you can pass in a
93 hash with configuration information. See the method descriptions
94 for more detail on what they mean.
95 data_folder => '/some/folder', # required
97 output_folder => '/some/http/folder', # required
98 expire => 300, # optional. default 300
99 width => 25, # optional. default 25
100 height => 35, # optional. default 35
101 images_folder => '/some/folder', # optional. default to lib dir
102 keep_failures => 0, # optional, defaults to 0(false)
103 debug => 0, # optional. default 0
104 "$md5sum = $captcha->generate_code( $number_of_characters );"
106 Creates a captcha. Image filename is "$md5sum.png"
107 It can also be called in array context to retrieve the string of
109 characters used to generate the captcha (the string the user is
110 expected to respond with). This is useful for debugging. ex.
111 "($md5sum,$chars) = $captcha->generate_code( $number_of_characters
113 );"
114 "$results = $captcha->check_code($code,$md5sum);"
116 check for a valid submitted captcha
117 $code is the submitted letter combination guess from the user
119 $md5sum is the submitted md5sum from the user (that we gave them)
121 If the $code and $md5sum are correct, the image file and database
123 entry will be removed.
124 If the $md5sum matches one in the database, and "keep_failures" is
126 false (the default), the image file and database entry will be
127 removed to avoid repeated attempts on the same captcha.
128 $results will be one of:
130 1 : Passed
132 0 : Code not checked (file error)
133 -1 : Failed: code expired
134 -2 : Failed: invalid code (not in database)
135 -3 : Failed: invalid code (code does not match crypt)
136 ACCESSOR METHODS
138 "$captcha->data_folder( '/some/folder' );"
139 Required. Sets the directory to hold the flatfile database that
140 will be used to store the current non-expired valid captcha
141 md5sum's. Must be writable by the process running the script
142 (usually the web server user, which is usually either "apache" or
143 "http"), but should not be accessable to the end user.
144 "$captcha->output_folder( '/some/folder' );"
146 Required. Sets the directory to hold the generated Captcha image
147 files. This is usually a web accessable directory so that the user
148 can view the images in here, but it doesn't have to be web
149 accessable (you could be attaching the images to an e-mail for some
150 verification, or some other Captcha implementation). Must be
151 writable by the process running the script (usually the web server
152 user, which is usually either "apache" or "http").
153 "$captcha->images_folder( '/some/folder' );"
155 Optional, and may greatly affect the results... use with caution.
156 Allows you to override the default character graphic png's and
157 backgrounds with your own set of graphics. These are used in the
158 generation of the final captcha image file. The defaults are held
159 in:
160 [lib install dir]/Authen/Captcha/images
161 "$captcha->expire( 300 );"
163 Optional. Sets the number of seconds this captcha will remain
164 valid. This means that the created captcha's will not remain valid
165 forever, just as long as you want them to be active. Set to an
166 appropriate value for your application. Defaults to 300.
167 "$captcha->width( 25 );"
169 Optional. Number of pixels high for the character graphics.
170 Defaults to 25.
171 "$captcha->height( 35 );"
173 Optional. Number of pixels wide for the character graphics.
174 Defaults to 35.
175 "$captcha->keep_failures( [0|1] );"
177 Optional. Defaults to zero. This option controls whether or not the
178 captcha will remain valid after a failed attempt. By default, we
179 only allow one attempt to solve it. This greatly reduces the
180 possibility that a bot could brute force a correct answer. Change
181 it at your own risk.
182 "$captcha->debug( [0|1|2] );"
184 Optional. Sets the debugging bit. 1 turns it on, 0 turns it off. 2
185 will print out verbose messages to STDERR.
186
188 sound file captcha: Incorporating distorted sound file creation.
189
191 The Captcha project:
192 http://www.captcha.net/
193 The origonal perl script this came from:
195 http://www.firstproductions.com/cgi/
196
198 Seth T. Jackson, <sjackson@purifieddata.net>
199 Josh I. Miller, <jmiller@purifieddata.net>
201 First Productions, Inc. created the cgi-script distributed under the
203 GPL which was used as the basis for this module. Much work has gone
204 into making this more robust, and suitable for other applications, but
205 much of the origonal code remains.
206
208 Copyright 2003, First Productions, Inc. (FIRSTPRODUCTIONS HUMAN TEST
209 1.0)
210 Copyright 2003 by Seth Jackson
212 This library is free software; you can redistribute it and/or modify it
214 under the terms of the GNU General Public License as published by the
215 Free Software Foundation; either version 2 of the License, or (at your
216 option) any later version. (see license.txt).
217 This program is distributed in the hope that it will be useful, but
219 WITHOUT ANY WARRANTY; without even the implied warranty of
220 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
221 General Public License for more details.
222 You should have received a copy of the GNU General Public License along
224 with this program; if not, write to the Free Software Foundation, Inc.,
225 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
226perl v5.12.0 2010-04-29 Captcha(3)