Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Captcha(3)	      User Contributed Perl Documentation	    Captcha(3)

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

SYNOPSIS
	 use Authen::Captcha;

	 # create a new	object
	 my $captcha = Authen::Captcha->new();

	 # set the data_folder.	contains flatfile db to	maintain state
	 $captcha->data_folder('/some/folder');

	 # set directory to hold publicly accessible images
	 $captcha->output_folder('/some/http/folder');

	 # Alternitively, any of the methods to	set variables may also be
	 # used	directly in the	constructor

	 my $captcha = Authen::Captcha->new(
	   data_folder => '/some/folder',
	   output_folder => '/some/http/folder',
	   );

	 # create a captcha. Image filename is "$token.png"
	 my $token = $captcha->generate_code($number_of_characters);

	 # check for a valid submitted captcha
	 #   $code is the submitted letter combination guess from the user
	 #   $token is the submitted token from	the user (that we gave them)
	 my $results = $captcha->check_code($code,$token);
	 # $results will be one	of:
	 #	    1 :	Passed
	 #	    0 :	Code not checked (file error)
	 #	   -1 :	Failed:	code expired
	 #	   -2 :	Failed:	invalid	code (not in database)
	 #	   -3 :	Failed:	invalid	code (code does	not match token)
	 ##############

WARNING
       The captcha produced by this module is rather weak compared to other
       modules available. You are advised to update to GD::SecurityImage,
       which provides API-compatible interface in GD::SecurityImage::AC
       module.

ABSTRACT
       Authen::Captcha provides	an object oriented interface to	captcha	file
       creations.  Captcha stands for Completely Automated Public Turing test
       to tell Computers and Humans Apart. A Captcha is	a program that can
       generate	and grade tests	that:

	   - most humans can pass.
	   - current computer programs can't pass

       The most	common form is an image	file containing	distorted text,	which
       humans are adept	at reading, and	computers (generally) do a poor	job.
       This module currently implements	that method. We	plan to	add other
       methods,	such as	distorted sound	files, and plain text riddles.

REQUIRES
	   GD	       (see http://search.cpan.org/~lds/GD-2.11/)
	   Digest::MD5 (standard perl module)

       In most common situations, you'll also want to have:

	A web server (untested on windows, but it should work)
	cgi-bin	or mod-perl access
	Perl: Perl 5.00503 or later must be installed on the web server.
	GD.pm (with PNG	support)

INSTALLATION
       Download	the zipped tar file from:

	   http://search.cpan.org/search?dist=Authen-Captcha

       Unzip the module	as follows or use winzip:

	   tar -zxvf Authen-Captcha-1.xxx.tar.gz

       The module can be installed using the standard Perl procedure:

	   perl	Makefile.PL
	   make
	   make	test
	   make	install	   # you need to be root

       Windows users without a working "make" can get nmake from:

	   ftp://ftp.microsoft.com/Softlib/MSLFILES/nmake15.exe

METHODS
   MAIN	METHODS
       "$captcha = Authen::Captcha->new();"
	   This	creates	a new Captcha object.  Optionally, you can pass	in a
	   hash	with configuration information.	 See the method	descriptions
	   for more detail on what they	mean.

	      data_folder => '/some/folder', # required
	      output_folder => '/some/http/folder', # required
	      expire =>	300, # optional. default 300
	      width =>	25, # optional.	default	25
	      height =>	35, # optional.	default	35
	      images_folder => '/some/folder', # optional. default to lib dir
	      keep_failures => 0, # optional, defaults to 0(false)
	      debug => 0, # optional. default 0

       "$token = $captcha->generate_code( $number_of_characters	);"
	   Creates a captcha. Image filename is	"$token.png"

	   It can also be called in array context to retrieve the string of
	   characters used to generate the captcha (the	string the user	is
	   expected to respond with). This is useful for debugging.  ex.

	   "($token,$chars) = $captcha->generate_code( $number_of_characters
	   );"

       "$results = $captcha->check_code($code,$token);"
	   check for a valid submitted captcha

	   $code is the	submitted letter combination guess from	the user

	   $token is the submitted token from the user (that we	gave them)

	   If the $code	and $token are correct,	the image file and database
	   entry will be removed.

	   If the $token matches one in	the database, and "keep_failures" is
	   false (the default),	the image file and database entry will be
	   removed to avoid repeated attempts on the same captcha.

	   $results will be one	of:

	       1 : Passed
	       0 : Code	not checked (file error)
	      -1 : Failed: code	expired
	      -2 : Failed: invalid code	(not in	database)
	      -3 : Failed: invalid code	(code does not match token)

   ACCESSOR METHODS
       "$captcha->data_folder( '/some/folder' );"
	   Required. Sets the directory	to hold	the flatfile database that
	   will	be used	to store the current non-expired valid captcha tokens.
	   Must	be writable by the process running the script (usually the web
	   server user,	which is usually either	"apache" or "http"), but
	   should not be accessible to the end user.

       "$captcha->output_folder( '/some/folder'	);"
	   Required. Sets the directory	to hold	the generated Captcha image
	   files. This is usually a web	accessible directory so	that the user
	   can view the	images in here,	but it doesn't have to be web
	   accessible (you could be attaching the images to an e-mail for some
	   verification, or some other Captcha implementation).	 Must be
	   writable by the process running the script (usually the web server
	   user, which is usually either "apache" or "http").

       "$captcha->images_folder( '/some/folder'	);"
	   Optional, and may greatly affect the	results... use with caution.
	   Allows you to override the default character	graphic	png's and
	   backgrounds with your own set of graphics. These are	used in	the
	   generation of the final captcha image file. The defaults are	held
	   in:
	       [lib install dir]/Authen/Captcha/images

       "$captcha->expire( 300 );"
	   Optional. Sets the number of	seconds	this captcha will remain
	   valid. This means that the created captcha's	will not remain	valid
	   forever, just as long as you	want them to be	active.	Set to an
	   appropriate value for your application. Defaults to 300.

       "$captcha->width( 25 );"
	   Optional. Number of pixels high for the character graphics.
	   Defaults to 25.

       "$captcha->height( 35 );"
	   Optional. Number of pixels wide for the character graphics.
	   Defaults to 35.

       "$captcha->keep_failures( [0|1] );"
	   Optional. Defaults to zero. This option controls whether or not the
	   captcha will	remain valid after a failed attempt. By	default, we
	   only	allow one attempt to solve it. This greatly reduces the
	   possibility that a bot could	brute force a correct answer. Change
	   it at your own risk.

       "$captcha->debug( [0|1|2] );"
	   Optional.  Sets the debugging bit. 1	turns it on, 0 turns it	off. 2
	   will	print out verbose messages to STDERR.

TODO
       sound file captcha: Incorporating distorted sound file creation.

SEE ALSO
       The Captcha project:
	   http://www.captcha.net/

       The origonal perl script	this came from:
	   http://www.firstproductions.com/cgi/

AUTHORS
       Seth T. Jackson,	<sjackson@purifieddata.net>

       Josh I. Miller, <jmiller@purifieddata.net>

       First Productions, Inc. created the cgi-script distributed under	the
       GPL which was used as the basis for this	module.	Much work has gone
       into making this	more robust, and suitable for other applications, but
       much of the origonal code remains.

       Fixes were reported and contributed by various people, see Changes file
       for a complete list.

COPYRIGHT AND LICENSE
       Copyright 2003, First Productions, Inc. (FIRSTPRODUCTIONS HUMAN TEST
       1.0)

       Copyright 2003 by Seth Jackson

       Copyright 2012 by Paolo Rossi, Lubomir Rintel, Chris Dunlop, Gert
       Schepens	and Ernesto HernA!ndez-Novich

       This library is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either	version	2 of the License, or (at your
       option) any later version. (see license.txt).

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE. See	the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with this program; if not, write	to the Free Software Foundation, Inc.,
       59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 764:
	   Non-ASCII character seen before =encoding in	'HernA!ndez-Novich'.
	   Assuming UTF-8

perl v5.32.1			  2014-03-12			    Captcha(3)

NAME | SYNOPSIS | WARNING | ABSTRACT | REQUIRES | INSTALLATION | METHODS | TODO | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Authen::Captcha&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help