Lockout plugin for SquirrelMail
===============================
Ver 1.4, 2007/07/12

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


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

This plugin allows you to create a list of users and/or 
domains that should be disallowed (or allowed) login 
access to SquirrelMail.  

It also allows you to block brute-force password guessing 
attacks, although please note that this will ONLY help
fight such attacks in the SquirrelMail interface, and 
should really be implemented in your mail system's 
authentication backend.  

Tips on implementing this kind of security measure in the
mail server's authentication backend:  

For Unix-like systems, there is a high probability that 
your backend authentication method is PAM.  For PAM-based 
authentication, look at the pam_tally or pam_lockout add-on 
modules, both of which will prevent this kind of attack 
in a much more robust manner.

For OpenLDAP-based authentication, you would set 
ppolicy_use_lockout and related configuration parameters 
(all the ppolicy parameters are password related) in the 
openldap configuration.



License
=======

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



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

  * SquirrelMail version 1.4.1 or above
  * Compatibility plugin version 2.0.7 or above



Security Considerations
=======================

When configuring IP-based blacklisting with 
$max_login_attempts_per_IP, username-based blacklisting
with $max_login_attempts, or adding a CAPTCHA requirement
with $activate_CAPTCHA_after_failed_attempts, you should
carefully consider your users' habits and the kinds of 
potential attacks you are trying to mitigate.

The most risk-free of these features is to configure the
CAPTCHA plugin to activate after a certain number of 
failed login attempts.  This makes SquirrelMail somewhat
harder to attack in an automated fashion while not creating
any need for the administrator to have to manually unlock
any account or IP address.  If you use a very strong 
CAPTCHA backend (beware, however, that most CAPTCHA
implementations are not very strong) and are only fighting 
off an *automated* attack, this step alone may suffice.

Adding IP-based blacklisting is effective at blocking an 
attacker who is trying multiple user account names as long 
as it is triggered at a reasonably high level of login 
failures (the threshold should be especially high if you 
have a lot of users who log in from a small number of 
client addresses).  

Username-based blacklisting could be useful when an attacker
is targetting a known user or small group thereof, although
because locking the user's account is also inconvenient to 
the legitimate user, IP-based blacklisting will usually 
still be a better solution.  However, if this feature is set 
with a fairly high threshold (higher than all others), it 
can be used to halt someone who consistently attacks the 
same account from a range of IP addresses.  After triggering 
a lockdown on such an account, it might be prudent to change 
the username or take other (real world?) measures.

See the configuration file for more information about how
to configure each of the settings discussed above.

If your SquirrelMail installation resides behind a proxy
server that sends X_FORWARDED_* headers, you should turn on
$obey_x_forwarded_headers, but in all other environments,
please leave this setting off, otherwise an attacker might
be able to thwart a domain lockout rule by tampering with
the request headers.

In the same vien, if a client is able to forge the regular
HTTP_HOST request header, domain-based lockout rules 
defined in the lockout table may be compromised.  The only 
solution for this kind of problem beside using user-based
lockout rules or enforcing login restrictions in the IMAP
server (which is ALWAYS more robust than implementing them
in the mail client) is to make sure that your usernames are 
in the format of a full email address (that is, that they 
always carry a domain name in them, and are not, for 
instance, in the same format as local account usernames).



Configuration
=============

Please copy the sample configuration (config.sample.php) 
file in this plugin's data sub-directory to your own
config.php and then edit it as necessary.  If you choose
to enable the $use_lockout_rules setting, you must also
copy the sample lockout table (lockout_table.sample.php)
in the data sub-directory into your own lockout_table.php
and edit it as follows:

Users and domains can be indicated using wildcards and can 
each have their own page that will be displayed when they 
are locked out.  See the sample lockout_table.sample.php 
file in the data directory for help building this table.  
You may want to edit the file(s) you have indicated as the 
target lockout page to be displayed in order to customize 
the message that will be seen when someone is locked out, or
send them to a special web page elsewhere or redirect them
to the standard SquirrelMail "bad username or password"
error page if you desire this plugin to be more stealthy.  
Note that this will typically catch locked out users no 
matter which of your domains they attempt to log in through.  

Note also that if you enable reverse lockout functionality,
the users and domains listed in the lockout table will all
be ALLOWED to log in, all OTHERS will be locked out.



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



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

  v1.4  2007/07/12  Paul Lesniewski <paul@squirrelmail.org>
   * Added ability to disable accounts that have too
     many successive login failures, including 
     optional administrative alert email
   * Added IP-based blacklisting
   * Added ability to enable the CAPTCHA plugin 
     for IP addresses that have too many successive
     login failures
   * Move lockout check to hook that occurs BEFORE 
     user is actually logged in
   * Updated for compatibility with SM 1.5.2+
   * Updated for use with new Compatibility plugin
   * Miscellaneous cleanup
   * Security considerations/audit thanks to Ben at reCAPTCHA.net

  1.3 -  Paul Lesniewski <paul@squirrelmail.org>
   * Added abilty to reverse lockout functionality
     (lock out everyone *except* those listed in the
     lockout table)

  1.2 -  Paul Lesniewski <paul@squirrelmail.org>
   * Fixed typo in INSTALL

  1.1 -  Paul Lesniewski <paul@squirrelmail.org>
   * Added ability to redirect to another web page or
     to the standard SquirrelMail "bad username or 
     password" page (with simulated bad login delay)

  1.0 -  Paul Lesniewski <paul@squirrelmail.org>
   * Initial release



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

   *  Ideas?

