Lockout plugin for SquirrelMail
===============================
Ver 1.6, 2008/04/01


Copyright (c) 2008 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 COPYING for details).



Donations
=========

If you or your company make regular use of this software, please
consider supporting Open Source development by donating to the authors
or inquire about hiring them to consult on other projects.  Donation
links for the author(s) are as follows:

Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228



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

  * SquirrelMail version 1.4.1 or above

  * Compatibility plugin version 2.0.11 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.



Troubleshooting
===============

  * If you have some SMTP authentication method configured
    in the main SquirrelMail configuration (or perhaps
    POP before SMTP is turned on) and administrative alert
    emails are not getting sent when a user is locked out,
    this is because the SMTP authentication credentials
    are not yet available before a user has logged in, so
    you need to provide administrative credentials for
    sending such emails.  See $lockout_smtp_auth_mech
    (and related settings) in the configuration file.



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

Before looking for help elsewhere, please try to help yourself:

  * Read the Troubleshooting section herein.

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.

  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal
    address(es), but please be patient with the mailing list.



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

  v1.6  2008/04/01  Paul Lesniewski <paul@squirrelmail.org>
   * Allow overrides of SquirrelMail SMTP/Sendmail settings 
     when sending administrative alert emails

  v1.5  2008/03/11  Paul Lesniewski <paul@squirrelmail.org>
   * Updated to use sq_send_mail for notification messages
   * Added ability to log lockout events in Squirrel Logger plugin
   * Remove use of login_top hook

  v1.4.1  2007/08/24  Paul Lesniewski <paul@squirrelmail.org>
   * Very small change due to change in SM 1.5.2; does not affect
     plugin functionality - no upgrade needed for anyone who does 
     not want to bother

  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?