README
1NAME
2 Authen::Captcha - Perl extension for creating captcha's to verify the
3 human element in transactions.
4
5SYNOPSIS
6 use Authen::Captcha;
7
8 # create a new object
9 my $captcha = Authen::Captcha->new();
10
11 # set the data_folder. contains flatfile db to maintain state
12 $captcha->data_folder('/some/folder');
13
14 # set directory to hold publicly accessable images
15 $captcha->output_folder('/some/http/folder');
16
17 # Alternitively, any of the methods to set variables may also be
18 # used directly in the constructor
19
20 my $captcha = Authen::Captcha->new(
21 data_folder => '/some/folder',
22 output_folder => '/some/http/folder',
23 );
24
25 # create a captcha. Image filename is "$md5sum.png"
26 my $md5sum = $captcha->generate_code($number_of_characters);
27
28 # check for a valid submitted captcha
29 # $code is the submitted letter combination guess from the user
30 # $md5sum is the submitted md5sum from the user (that we gave them)
31 my $results = $captcha->check_code($code,$md5sum);
32 # $results will be one of:
33 # 1 : Passed
34 # 0 : Code not checked (file error)
35 # -1 : Failed: code expired
36 # -2 : Failed: invalid code (not in database)
37 # -3 : Failed: invalid code (code does not match crypt)
38 ##############
39
40ABSTRACT
41 Authen::Captcha provides an object oriented interface to captcha file
42 creations. Captcha stands for Completely Automated Public Turning test
43 to tell Computers and Humans Apart. A Captcha is a program that can
44 generate and grade tests that:
45
46 - most humans can pass.
47 - current computer programs can't pass
48
49 The most common form is an image file containing distorted text, which
50 humans are adept at reading, and computers (generally) do a poor job.
51 This module currently implements that method. We plan to add other
52 methods, such as distorted sound files, and plain text riddles.
53
54REQUIRES
55 GD (see http://search.cpan.org/~lds/GD-2.11/)
56 Digest::MD5 (standard perl module)
57
58 In most common situations, you'll also want to have:
59
60 A web server (untested on windows, but it should work)
61 cgi-bin or mod-perl access
62 Perl: Perl 5.00503 or later must be installed on the web server.
63 GD.pm (with PNG support)
64
65INSTALLATION
66 Download the zipped tar file from:
67
68 http://search.cpan.org/search?dist=Authen-Captcha
69
70 Unzip the module as follows or use winzip:
71
72 tar -zxvf Authen-Captcha-1.xxx.tar.gz
73
74 The module can be installed using the standard Perl procedure:
75
76 perl Makefile.PL
77 make
78 make test
79 make install # you need to be root
80
81 Windows users without a working "make" can get nmake from:
82
83 ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe
84
85METHODS
86 MAIN METHODS
87
88 "$captcha = Authen::Captcha->new();"
89 This creates a new Captcha object. Optionally, you can pass in a
90 hash with configuration information. See the method descriptions for
91 more detail on what they mean.
92
93 data_folder => '/some/folder', # required
94 output_folder => '/some/http/folder', # required
95 expire => 300, # optional. default 300
96 width => 25, # optional. default 25
97 height => 35, # optional. default 35
98 images_folder => '/some/folder', # optional. default to lib dir
99 debug => 0, # optional. default 0
100
101 "$md5sum = $captcha->generate_code( $number_of_characters );"
102 Creates a captcha. Image filename is "$md5sum.png"
103
104 It can also be called in array context to retrieve the string of
105 characters used to generate the captcha (the string the user is
106 expected to respond with). This is useful for debugging. ex.
107
108 "($md5sum,$chars) = $captcha->generate_code( $number_of_characters
109 );"
110
111 "$results = $captcha->check_code($code,$md5sum);"
112 check for a valid submitted captcha $code is the submitted letter
113 combination guess from the user $md5sum is the submitted md5sum from
114 the user (that we gave them) $results will be one of:
115
116 1 : Passed
117 0 : Code not checked (file error)
118 -1 : Failed: code expired
119 -2 : Failed: invalid code (not in database)
120 -3 : Failed: invalid code (code does not match crypt)
121
122 ACCESSOR METHODS
123
124 "$captcha->data_folder( '/some/folder' );"
125 Required. Sets the directory to hold the flatfile database that will
126 be used to store the current non-expired valid captcha md5sum's.
127 Must be writable by the process running the script (usually the web
128 server user, which is usually either "apache" or "http"), but should
129 not be accessable to the end user.
130
131 "$captcha->output_folder( '/some/folder' );"
132 Required. Sets the directory to hold the generated Captcha image
133 files. This is usually a web accessable directory so that the user
134 can view the images in here, but it doesn't have to be web
135 accessable (you could be attaching the images to an e-mail for some
136 verification, or some other Captcha implementation). Must be
137 writable by the process running the script (usually the web server
138 user, which is usually either "apache" or "http").
139
140 "$captcha->images_folder( '/some/folder' );"
141 Optional, and may greatly affect the results... use with caution.
142 Allows you to override the default character graphic png's and
143 backgrounds with your own set of graphics. These are used in the
144 generation of the final captcha image file. The defaults are held
145 in: [lib install dir]/Authen/Captcha/images
146
147 "$captcha->expire( 300 );"
148 Optional. Sets the number of seconds this captcha will remain valid.
149 This means that the created captcha's will not remain valid forever,
150 just as long as you want them to be active. Set to an appropriate
151 value for your application. Defaults to 300.
152
153 "$captcha->width( 25 );"
154 Optional. Number of pixels high for the character graphics. Defaults
155 to 25.
156
157 "$captcha->height( 35 );"
158 Optional. Number of pixels wide for the character graphics. Defaults
159 to 35.
160
161 "$captcha->debug( [0|1|2] );"
162 Optional. Sets the debugging bit. 1 turns it on, 0 turns it off. 2
163 will print out verbose messages to STDERR.
164
165TODO
166 sound file captcha: Incorporating distorted sound file creation.
167
168SEE ALSO
169 The Captcha project: http://www.captcha.net/
170
171 The origonal perl script this came from:
172 http://www.firstproductions.com/cgi/
173
174AUTHORS
175 Seth T. Jackson, <sjackson@purifieddata.net>
176
177 Josh I. Miller, <jmiller@purifieddata.net>
178
179 First Productions, Inc. created the cgi-script distributed under the GPL
180 which was used as the basis for this module. Much work has gone into
181 making this more robust, and suitable for other applications, but much
182 of the origonal code remains.
183
184COPYRIGHT AND LICENSE
185 Copyright 2003, First Productions, Inc. (FIRSTPRODUCTIONS HUMAN TEST
186 1.0)
187
188 Copyright 2003 by Seth Jackson
189
190 This library is free software; you can redistribute it and/or modify it
191 under the terms of the GNU General Public License as published by the
192 Free Software Foundation; either version 2 of the License, or (at your
193 option) any later version. (see license.txt).
194
195 This program is distributed in the hope that it will be useful, but
196 WITHOUT ANY WARRANTY; without even the implied warranty of
197 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
198 Public License for more details.
199
200 You should have received a copy of the GNU General Public License along
201 with this program; if not, write to the Free Software Foundation, Inc.,
202 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
203
204
