=====================================
= Flickr-CAPTCHA
=====================================

Table of Contents

1. Overview
2. Copyright
3. License
4. Installation Instructions
5. Configuration
6. Acknowledgements

=====================================

1. Overview

Flickr-CAPTCHA is a captcha program that uses flickr images and tags 
to decide whether someone is human. A random thing is selected (from a 
list of things) and a random number of flickr images are chosen
a long with a set of decoys. Each decoy contains at least one other 
thing in order to prevent images that are ambigious and to try and keep
it obvious they are decoys. The user must then select all images and 
if they get 50% right (with minus marks for wrong answers) we consider
them definitely human. It should be quite difficult for a computer
to guess which images to select but fun and enjoyable for a human. It
requires only very basic english skills. 

*SECURITY*

Image ID's are hashed then proxied through a PHP page so that a bot
cannot simply lookup the image themselves through the flickr API. They
could potentially use the author and the title so an option exists to 
hide the title as well if you are paranoid. You will also want to 
adjust the acceptedRatio if you are really paranoid.

*IMAGE LICENSING*

We are only selecting images that have attribution licenses, not those 
that are all rights reserved. Every image being displayed is attributed
to the author with a link to their flickr page. I am not a lawyer, see
the LICENSE file for warranty (hint: there is none). 

Pros
    - Fun and easy to use
    - Easy for human / hard for computer
    - Customizable

Cons
    - Slow to load all the images
    - Not secure

2. Copyright

This program is copyright Joel Heenan (joelh at planetjoel dot com) 2008

3. License

Please see the file "LICENSE"

This program 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 3 of the License, or
(at your option) any later version.

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, see <http://www.gnu.org/licenses/>.

4. Installation Instructions

4.0 Requirements

- Flickr API key
- JQuery

4.1 Obtain API key

Visit http://www.flickr.com/services/api/misc.api_keys.html and apply
for a flickr API key. Edit the file flickr_captcha.class.php and change
the apikey variable

4.2 Place files on your web server

Place files: 

flickr_captcha.class.php
flickr.captcha.css
flickr.captcha.js

On your website in a structure that suits you. You may wish to place the 
CSS file with other stylesheets, or you may wish to bundle them 
all together in a flickr_captcha directory. Up to you.

4.3 Download JQuery

Visit http://jquery.com/ and download the latest stable JQuery
Be sure to load it before loading the flickr.captcha.js script file

4.4 Integrate existing forms with Captcha

Using file flickr.class.tester.php as an example integrate with your own
website. You will need to add

 - Link to the stylesheet
 - Link to the javascript source
 - A session_start() somewhere near the beginning of your PHP script

It is a good idea to display the captcha only once the user has indicated
they are intending to perform some action. One downside of Flickr-CAPTCHA
is that it requires a lot of images to download which could slow down 
your website dramatically. 

You then need to instantiate a flickr_captcha() object. Then use 
validate_submit() to decide how to proceed, and display_form()
to display the captcha.

5. Configuration

There are a whole bunch of things documented in the 
flickr_captcha.class.php you may wish to change. 

If for some reason you wish to change the output HTML look and feel the 
_outputHTML() private function is where this is all done. 

6. Acknowledgements

Microsoft for ASIRRA from which some UI ideas were borrowed.
http://research.microsoft.com/en-us/um/redmond/projects/asirra/

Horst Nogajski for hn_captcha class. I used Horst's API for this 
project so that I could drop and replace my class with his on my
website.