1Captcha(3)            User Contributed Perl Documentation           Captcha(3)
2
3
4

NAME

6       Authen::Captcha - Perl extension for creating captcha's to verify the
7       human element in transactions.
8

SYNOPSIS

10         use Authen::Captcha;
11
12         # create a new object
13         my $captcha = Authen::Captcha->new();
14
15         # set the data_folder. contains flatfile db to maintain state
16         $captcha->data_folder('/some/folder');
17
18         # set directory to hold publicly accessible images
19         $captcha->output_folder('/some/http/folder');
20
21         # Alternitively, any of the methods to set variables may also be
22         # used directly in the constructor
23
24         my $captcha = Authen::Captcha->new(
25           data_folder => '/some/folder',
26           output_folder => '/some/http/folder',
27           );
28
29         # create a captcha. Image filename is "$token.png"
30         my $token = $captcha->generate_code($number_of_characters);
31
32         # 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

WARNING

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

ABSTRACT

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
56           - most humans can pass.
57           - current computer programs can't pass
58
59       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

REQUIRES

65           GD          (see http://search.cpan.org/~lds/GD-2.11/)
66           Digest::MD5 (standard perl module)
67
68       In most common situations, you'll also want to have:
69
70        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

INSTALLATION

76       Download the zipped tar file from:
77
78           http://search.cpan.org/search?dist=Authen-Captcha
79
80       Unzip the module as follows or use winzip:
81
82           tar -zxvf Authen-Captcha-1.xxx.tar.gz
83
84       The module can be installed using the standard Perl procedure:
85
86           perl Makefile.PL
87           make
88           make test
89           make install    # you need to be root
90
91       Windows users without a working "make" can get nmake from:
92
93           ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
94

METHODS

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
102              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
111       "$token = $captcha->generate_code( $number_of_characters );"
112           Creates a captcha. Image filename is "$token.png"
113
114           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
118           "($token,$chars) = $captcha->generate_code( $number_of_characters
119           );"
120
121       "$results = $captcha->check_code($code,$token);"
122           check for a valid submitted captcha
123
124           $code is the submitted letter combination guess from the user
125
126           $token is the submitted token from the user (that we gave them)
127
128           If the $code and $token are correct, the image file and database
129           entry will be removed.
130
131           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
135           $results will be one of:
136
137               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
143   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
151       "$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
160       "$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
168       "$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
174       "$captcha->width( 25 );"
175           Optional. Number of pixels high for the character graphics.
176           Defaults to 25.
177
178       "$captcha->height( 35 );"
179           Optional. Number of pixels wide for the character graphics.
180           Defaults to 35.
181
182       "$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
189       "$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

TODO

194       sound file captcha: Incorporating distorted sound file creation.
195

SEE ALSO

197       The Captcha project:
198           http://www.captcha.net/
199
200       The origonal perl script this came from:
201           http://www.firstproductions.com/cgi/
202

AUTHORS

204       Seth T. Jackson, <sjackson@purifieddata.net>
205
206       Josh I. Miller, <jmiller@purifieddata.net>
207
208       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
213       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
220       Copyright 2003 by Seth Jackson
221
222       Copyright 2012 by Paolo Rossi, Lubomir Rintel, Chris Dunlop, Gert
223       Schepens and Ernesto Hernández-Novich
224
225       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
230       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
235       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

POD ERRORS

240       Hey! The above document had some coding errors, which are explained
241       below:
242
243       Around line 764:
244           Non-ASCII character seen before =encoding in 'Hernández-Novich'.
245           Assuming UTF-8
246
247
248
249perl v5.38.0                      2023-07-20                        Captcha(3)
Impressum