CAPTCHA plugin for SquirrelMail
===============================
Ver 1.0, 2007/05/30

Original authors: Paul Lesniewski <paul@squirrelmail.org>


Description
===========

This plugin places a CAPTCHA (Completely Automated Public 
Turing to tell Computers from Humans Apart) input on the 
login screen that is used to detect whether or not a human 
is attempting to log in.  This helps prevent automated 
login attacks.

More than one type of CAPTCHA implementation is available 
and more can be added with little trouble.  Each one is
called a "backend" and has a unique name that identifies
it in the configuration file.  Which one you use may depend
upon personal preference as well as the available PHP 
extensions or other software available on your server.

Note that before you use this plugin, please be aware of
the accessibility problems associated with CAPTCHA systems.
See:  http://www.w3.org/TR/turingtest/
      http://en.wikipedia.org/wiki/Captcha#Accessibility

Also be aware that CAPTCHA technology is ever evolving as
is the technology that is able to defeat many CAPTCHA
implementations.  Several of the backends that come with
this plugin are surely hackable by determined persons.

Finally note that because the CAPTCHA challenge code
(correct answer) changes every time you attempt to log
in, brute-force attacks against this plugin are rendered 
ineffective.  However, if you want to try and slow down
an attacker that nevertheless continues to try to enter
random answers, the Lockout plugin (version 1.4+) is 
compatible with this plugin and can be used to stop 
accepting login attempts after so many failed tries.  
The best use of the CAPTCHA plugin might be to keep it 
hidden from regular users unless one fails to enter a 
correct password after several tries - the Lockout plugin 
can also be configured to do just that - turn on the 
CAPTCHA plugin only under this kind of circumstance when 
it is most desirable/useful (if used in that manner,
remember NOT to enable the CAPTCHA plugin in the 
SquirrelMail configuration; the Lockout plugin will do
so automatically on an as-needed basis).



License
=======

This plugin is released under the GNU General Public
License (see the file COPYING for details).



Requirements
============

  * SquirrelMail version 1.2.9 or above
  * Compatibility plugin version 2.0.7 or above, unless
    using SquirrelMail 1.5.2+ or 1.4.10+



Help Requests
=============

Help requests are welcome at my personal email address, but I
request that you first post to the SquirrelMail Plugins mailing
list, where you'll get faster help from more people and other
people with the same problem will be able to see how your issue
was resolved.  If you don't get good answers that way, you may
try emailing me directly.

Info about the SquirrelMail Plugins mailing list can be found
on the SquirrelMail web site.  It is currently located at:

http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
squirrelmail-plugins@lists.sourceforge.net



Adding Backends
===============

If you have a new CAPTCHA implementation, we'd love to add it.
You need to give it a name (for example "my_captcha") and create
a directory with the same name inside the "backends" subdirectory
of this plugin.  Inside of your new directory, then create a file 
named <backend name>.php (in this example, the path to your backend
file would be "plugins/captcha/backends/my_captcha/my_captcha.php") 
with the following functions in it:  

  * <backend name>_show_input_widgets()
    In this example, it would be called "my_captcha_show_input_widgets()".
    This function is responsible for creating the information that will
    be displayed on the login page - typically, this would be a CAPTCHA
    image and textual input element.  The output MUST NOT be sent to
    the browser, and instead returned to the caller.  Please be careful 
    to build your output correctly for both all SquirrelMail versions 
    (templated output is handled somewhat differently).  You should be 
    able to copy most all of the code that is provided with any of the 
    other backends herein.

  * <backend name>_validate_captcha()
    In this example, it would be called "my_captcha_validate_captcha()".
    This function is responsible for testing the user's input against
    the CAPTCHA's correct response value.  The function must return a
    boolean TRUE or FALSE, where TRUE indicates that the user entered
    the correct CAPTCHA response.

  * <backend name>_check_configuration()
    In this example, it would be called "my_captcha_check_configuration()".
    This function is run during the execution of SquirrelMail's 
    src/configtest.php script and may be used to ensure that any required 
    dependencies or configuration values are correctly set up by the 
    SquirrelMail administrator.  This function is entirely optional (the 
    others are NOT), but if implemented, it must return FALSE if there 
    are no setup problems, or TRUE if there are some issues that must be 
    fixed by the administrator.  If there are problems, you are encouraged 
    to use the do_err() function to display them.

Also note that if your backend has any configurable settings, you can
create a file called <backend name>_config.sample.php in your backend
directory, which will be loaded for you unless the user has copied it 
to <backend name>_config.php, in which case that file will be loaded 
instead.  Your backend functions may then assume that the global values 
therein will always be available for use.

Only GPL-licensed backends will be added to this plugin.



Future Work
===========

   *  Add reporting capability to squirrel_logger plugin for failures
      (or success?) with this plugin - one request was to know, when
      failed, if anything was input at all, and because the user input
      is always called captcha_response, this might be easy, EXCEPT
      in the case of the recaptcha backend, where it's called 
      recaptcha_challenge_field, so see what we can do with that....
   *  Ideas?



Change Log
==========

  1.0  2007/05/30  Paul Lesniewski <paul@squirrelmail.org>
   * Initial release



