Secure Login plugin for SquirrelMail
====================================
Ver 1.3, 2007/01/24

Authors: Graham Norbury <gnorbury@bondcar.com>
         Paul Lesniewski <paul@squirrelmail.org>


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

This plugin automatically enables a secure HTTPS/SSL-encrypted 
connection for the SquirrelMail login page if it hasn't already 
been requested by the referring hyperlink or bookmark.
Optionally, the secure connection can be turned off again after 
successful login.  This utility is intended to prevent passwords 
and email contents being transmitted over the Internet in the 
clear after people browse to the login page without including 
https:// in its address.



License
=======

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



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

  * SquirrelMail version 1.2.8 or above
  * HTTPS/SSL-capable web server with encryption already 
    working on your SquirrelMail installation



Hosting Multiple Sites With One Certificate
===========================================

One instance of the Apache web server listening on a single 
IP address can currently only serve up one SSL certificate.  
If you host more than one domain on a single server, you can 
serve this one certificate for all sites (users will get a 
warning about mismatched host names which can be accepted 
by the user), or you can play tricks with URIs, depending on 
how important it is to you not to cause the warning to be 
displayed to users.

One common tactic is to host your secure pages for all hosts 
on top of your main domain (to which the certificate officially 
belongs).  URIs would look like this:

https://www.maindomain.com/www.virtualdomain.com/webmail/src/login.php
https://www.maindomain.com/webmail/src/login.php?domain=www.virtualdomain.com

This plugin can support such URIs if you use the 
$allVirtualDomainsUnderOneSSLHost configuration setting.  If you 
take this approach, you will need to include an Alias similar to 
the following in the <VirtualHost> directive for the SSL (MAKE 
SURE it's the SSL virtual host directive and *not* the regular, 
non-SSL directive):

Alias /www.virtualdomain.com /var/www/html/maindomain/squirrelmail

You'll want to adjust the path in the Alias to point to your 
SquirrelMail installation, of course.  See config.php.sample 
for more information about configuring this plugin to use such 
URIs.



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

Your web server is assumed to be running Apache 1.3.x or 2.x with 
OpenSSL support (or similar).  Before enabling this plugin, you 
should ALREADY be able to browse to your SquirrelMail installation 
by using https://, so if not, please take care of your web server 
configuration before complicating matters with this plugin.

If you turn on $change_back_to_http_after_login under SquirrelMail 
1.5.2 and above, you will be unable to log in because by default, 
SquirrelMail 1.5 will only transmit cookies securely if the user's 
session started under https://.  If you really want to revert to an 
unencrypted connection after user login, you need to run the 
SquirrelMail configuration utility and change the "Only secure 
cookies if poss." setting (under "General Options") to "false".



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
==========

  1.3  2007/01/23  Paul Lesniewski <paul@squirrelmail.org>
   * Fix for problem with session variables sticking around between logins,
     such that SSL connection would be forced only every other login.  
   * Updated documentation.
   * Added configtest hook.
   * Updated for compatibility with SquirrelMail 1.5.x
   * Removed specific requirement for Compatibility plugin.
   * Updated to stop accessing superglobal arrays directly.
   * Removed configuration file requirement.
   * Added debug flag.
   * Added more flexible "multiple domains under one SSL certificate" 
     configuration.
   * Added more fine-grained controls over URI parsing (not recommended 
     unless default behavior won't work).
   * NOTE that configuration variable names have changed - please review 
     your config file if upgrading from an earlier release!

v1.2,  7/15/2003 : Changed plugin logic to detect HTTP and HTTPS connections
                   based on port number instead of environment variables 
                   that in some cases may not be provided by the web server
                   (Thanks to Tony Geerts <tgeerts@dyton.com>)
                   If user comes to login page with a URI that has any
                   GET variables appended to it, they are automatically
                   added to the secure redirection URI (Thanks to Alex 
                   Lemaresquier <alex@brainstorm.fr>).

v1.1,  7/12/2003 : Fix for when going back to HTTP from HTTPS login that
                   would cause javascript errors after sending at least
                   one message - the right frame was getting redirected
                   back to HTTPS.  But not any more.  ;>
                   This is only a fix applicable for SM 1.4 and up.
                   Updated for latest version reporting API.
                   Removed config.php from distribution, replaced with
                   config.php.sample for hassle-free upgrades.

v1.0,  3/03/2003 : Added compatibility with SquirrelMail v1.4.
                   New setup.php format for better overall SquirrelMail 
                   performance.
                   In combination with more recent versions of SquirrelMail,
                   (and probably older ones, thanks to the Compatibility plugin)
                   a bug that allowed users to log in without SSL in a browser
                   session that had already logged in once before has been 
                   removed.

v0.7,  2/26/2003 : Added config setting for servers running https or http
                   on non-standard ports.

v0.6,  12/7/2002 : Sites that host all their virtual domains off of a single
                   SSL URL can now specify that URL in setup.php and users
                   will be redirected as appropriate
                   PHP version checking fixed (for all locales)
                   (paul@squirrelmail.org)

v0.5,  11/5/2002 : Updated for compatibility with Plugin Updates plugin.
                   (paul@squirrelmail.org)

v0.4,  10/7/2002 : Added flag that allows users who came to the login page
                   using an encrypted connection to stay in an encrypted  
                   session (while others only get encryption just for the
                   login, assuming that flag is enabled)
                   (paul@squirrelmail.org)

v0.3,  8/14/2002 : Added functionality that sends user back to a non-encrypted
                   connection after logging in (it may be turned off at will).  
                   (paul@squirrelmail.org)

v0.2,  1/4/2002  : Eliminated use of SCRIPT_URI server variable which (apparently)
                   is only available when Apache mod_rewrite has been enabled 

                   Added loop counter to prevent endless redirects if for some
                   reason we end up back at the same page without HTTPS being set.

v0.1,  1/3/2002 :  Initial version

