NAME

Apache2::reCaptcha - reCaptcha based auth system using cookies.

SYNOPSIS

 # reCaptcha.conf
 PerlModule Apache2::reCaptcha
 PerlSetVar reCaptchaTicketDB DBI:mysql:database=sessions;host=mysql.example.com
 PerlSetVar reCaptchaTicketDBUser session
 PerlSetVar reCaptchaTicketDBPassword supersecret password
 PerlSetVar reCaptchaTicketTable tickets:ticket_hash:ts
 PerlSetVar reCaptchaTicketLoginHandler /reCaptchalogin
 #This is the path for the cookie
 PerlSetVar reCaptchaPath /
 PerlSetVar reCaptchaDomain www.example.com
 #only use if you want to force your URL to be SSL
 #PerlSetVar reCaptchaSecure 1
 PerlSetVar reCaptchaPublicKey biglongrandompublicstringfromrecaptchaproject
 PerlSetVar reCaptchaPrivateKey biglongandomprivatesringfromrecaptchaproject
 PerlSetVar reCaptchaHeaderTemplate /etc/apache2/recaptcha.header.inc
 PerlSetVar reCaptchaFooterTemplate /etc/apache2/recaptcha.footer.inc
 PerlSetVar reCaptchaLoginScript /reCaptchaloginform
 PerlSetVar reCaptchaCookieName reCaptcha
 #Having problems, tun on debugging
 #PerlSetVar AuthCookieDebug    5

 <Location /reCaptcha>
     AuthType Apache2::reCaptcha
     AuthName reCaptcha
     PerlAuthenHandler Apache2::reCaptcha->authenticate
     require valid-user
 </Location>
 
 <Location /reCaptchaloginform>
     AuthType Apache2::reCaptcha
     AuthName reCaptcha
     SetHandler perl-script
     PerlResponseHandler Apache2::reCaptcha->login_screen
 </Location>
 
 <Location /reCaptchalogin>
     AuthType Apache2::reCaptcha
     AuthName reCaptcha
     SetHandler perl-script
     PerlResponseHandler Apache2::reCaptcha->login
 </Location>
 
 <Location /reCaptcha/logout>
     AuthType Apache2::reCaptcha
     AuthName reCaptcha
     SetHandler perl-script
     PerlResponseHandler Apache2::reCaptcha->logout
 </Location>

DESCRIPTION

This Module uses the reCaptcha projects service to protect webresources from automated scripts that try to screen scrape your data. Often times adding a captcha check to a webapp requires recoding your app. This module puts the verifcation work into apache and makes it easy to use in multiple places on your website.Often times having to do captchas over and over will discourage people from wanting to use the app. This module will asign a cookie based ticket the first time you complete a captcha for a protected resource and expire after fifteen minutes requiring you to do another captcha. Since this is done using apache you can also white list IPs via Apaches 'Allow from/Deny From' syntax. This is helpful if your services need to be called from other resources.

This module has support for HTML templates to make it have the same look and feel as the rest of your website. Define reCaptchaHeaderTemplate and reCaptchaFooterTemplate. These template files will be prepended and appended to the reCaptcha code. Infact the reCaptcha interface look and feel can also be conigured. See the reCaptcha project page to figure out how to do this.

Why reCaptcha?

The reCaptcha project is more than just a great serice with accessability support. By using it you are helping the =head3 "/archive.org"" in <a href="http:Internet Archive</a>> to digitize books that OCR software can't seem to figure out.

CONFIGURATION

This module requires the following modules

 * Apache2::AuthTicet
 * Captcha::reCAPTCHA
 * CGI
 * DBD
 * DBI

You will also need to create the following tables in a database.

        CREATE TABLE IF NOT EXISTS `tickets` (
          `ticket_hash` char(32) NOT NULL,
          `ts` int(11) NOT NULL,
          PRIMARY KEY  (`ticket_hash`)
        ) ENGINE=MyISAM DEFAULT CHARSET=latin1;
        
        CREATE TABLE IF NOT EXISTS `ticketsecrets` (
          `sec_version` bigint(20) unsigned NOT NULL auto_increment,
          `sec_data` text NOT NULL,
          UNIQUE KEY `sec_version` (`sec_version`)
        ) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;
        

reCaptchaTicketDB

This is a standard perl DBI dsn see the DBI for a complete reference on how to set this up.

reCaptchaTicketDBUser

The Database username to login

reCaptchaTicketDBPassword

The database password

reCaptchaTicketTable

This is the path to where to store tickets the fomat is table:column1:column2

reCaptchaTicketLoginHandler

This is the (See the above example to define these settings).

reCaptchaPrivatKey

You will recieve a public key from the reCaptcha project once you sign up

reCaptchaPublicKey

You will recieve a public key from the reCaptcha project once you sign up

It's easier to place the main config (Like the above config) into a conf file and use Include to include it into your httpd.conf or virtual host config. This defines all the basic setup

BUGS

If you are using this with proxypass, you may have troubles getting it to work past the first level of the uri

CREDITS

Thanks to Michael Shout for is development of AuthTicket which did all the heavy lifting in this module and Perrin Harkins from the mod_perl mailing list for his help. Last but not least Andy Armstrong for his development of the recaptcha api.

AUTHOR

Aaron Collins <analogrithems@gmail.com>

SEE ALSO

Apache::AuthTicket

cpanm Apache2::reCaptcha

perl -MCPAN -e shell
install Apache2::reCaptcha