Secure Login plugin for SquirrelMail
====================================
Ver 1.4, 2008/05/12


Copyright (c) 2002 Graham Norbury <gnorbury@bondcar.com>
Copyright (c) 2002-2008 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).



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

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.4  2008/05/12  Paul Lesniewski <paul@squirrelmail.org>
    * When using $allVirtualDomainsUnderOneSSLHost and coming back
      from the signout page or a login error page, the URI was
      wrongly constructed - fixed thanks to Brett Johnson
    * Minor bug fixes and updates

  v1.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  2003/07/15  Paul Lesniewski <paul@squirrelmail.org>
    * 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  2003/07/12  Paul Lesniewski <paul@squirrelmail.org>
    * 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  2003/03/03  Paul Lesniewski <paul@squirrelmail.org>
    * 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  2003/02/26  Paul Lesniewski <paul@squirrelmail.org>
    * Added config setting for servers running https or http
      on non-standard ports.

  v0.6  2002/12/07  Paul Lesniewski <paul@squirrelmail.org>
    * 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)

  v0.5  2002/11/05  Paul Lesniewski <paul@squirrelmail.org>
    * Updated for compatibility with Plugin Updates plugin.

  v0.4  2002/10/07  Paul Lesniewski <paul@squirrelmail.org>
    * 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)

  v0.3  2002/08/14  Paul Lesniewski <paul@squirrelmail.org>
    * Added functionality that sends user back to a non-encrypted
      connection after logging in (it may be turned off at will).

  v0.2  2002/01/04  Graham Norbury <gnorbury@bondcar.com>
    * 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  2002/01/03  Graham Norbury <gnorbury@bondcar.com>
    * Initial version