One-Time Password plugin for SquirrelMail
=========================================
Ver 1.0, 2009/01/01


Copyright (c) 2008-2009 Paul Lesniewski <paul@squirrelmail.org>



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

This plugin is intended to decrease the risk of usernames and/or
passwords being stolen when users log in to their accounts from
untrusted locations.  Users can create a list of usernames and/or
passwords that will work one time only so that if stolen (during
or after the login process), they would pose no security risk.

However, there are certain security tradeoffs associated with
this functionality, so please be sure to read and understand
the security information below.

Amongst other configurable settings, the administrator can decide
to disable certain parts of the SquirrelMail interface when a
user is logged in using a one-time password.



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/wish list links for
the author(s) are as follows:

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



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

  * SquirrelMail version 1.4.18 -- Earlier versions can be used
    if certain patches are applied; for example, version 1.4.17
    can be used if the following two patches are applied in order:

       http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/options.php?view=patch&r1=13373&r2=13372&pathrev=13373
       http://squirrelmail.svn.sourceforge.net/viewvc/squirrelmail/branches/SM-1_4-STABLE/squirrelmail/functions/options.php?view=patch&r1=13378&r2=13377&pathrev=13378

  * Compatibility plugin version 2.0.9 or higher

  * [OPTIONAL] libmcrypt and the PHP mcrypt extension (--with-mcrypt)
    If you choose to use stronger password encryption methods, you'll
    need mcrypt support in PHP.  See:

       http://www.php.net/mcrypt



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

First, please consider that when using this plugin, users will
write down the temporary passwords they create, which in and of
itself may pose a greater security risk than when they use their
own (memorized) passwords.  To lessen this risk, you can create
a system-wide prefix that must be combined with any one-time
password that you should convey to users via some other mechanism
(and encourage them to memorize it and not write it down with
their password list).  But this is always a very real risk - that
passwords and/or prefixes will be written down and possibly stolen.

Because SquirrelMail is only a mail client, it does NOT control user
passwords.  Under normal operation, it merely takes usernames and
passwords from the user and passes them along to the IMAP server for
authentication.  Thus, in order to implement this plugin, passwords
need to be stored somewhere where SquirrelMail can see them (note
that this is in addition to your normal user data/password store in
the mail server).

And because SquirrelMail is an application that runs in the web
server, the web server needs to have access to the passwords that
are stored for use in this plugin.  This plugin stores the
password data with other user preference data.  This can be a big
risk, especially in shared hosting environments or on servers
running untrusted code or that are routinely broken into.  This
plugin provides a security model that helps reduce those risks,
but they cannot be eliminated entirely.

Passwords are encrypted using reasonably strong methods, especially
if PHP has mcrypt support.  The key component to keeping the two-way
nature of the encryption safe is the security of the hash phrase (or
encryption key) that is used to encrypt the passwords.

The best way to ensure that safety is to use the example Apache
configuration file to specify that hash phrase (and encryption method)
and put it in the web server's configuration directory (making sure
the file is only accessible to the root user).  In this scenario, that
very sensitive configuration data is read by the web server at startup
(while it is still running as the root superuser) and therafter it is
ONLY available to files and applications that are located within the
SquirrelMail directories, and is not readable by any non-root user.
Only if untrusted code is running from within the SquirrelMail
installaion directory can someone else decrypt user passwords.

If you do not control your web server configuration files, the best
thing to do may be to avoid using this plugin.  However, it is also
possible to store the cryptographic hash phrase (encryption key)
in the plugin configuration file.  This is MUCH LESS DESIRABLE and
POSES A SECURITY VULNERABILITY.  Any other user or application
running on the same server can then read the encryption configuration
and attempt to then steal user password data.  You should only use
this feature if you have absolute trust in the other processes that
are running on the web server.  You have been warned.



Encryption Configuration
========================

There are two ways that this plugin can encrypt user passwords.  One
is by using an internal PHP-based (rc4) algorithm.  The other is to 
use any one of mcrypt's algorithms.  Please note that once you decide
on one or the other, changing the method will render all previously
stored passwords unreadable.

It is recommended that you opt for the stronger algorithms provided
by mcrypt if at all possible, although this does require that you
add mcrypt support to PHP:

You will need to install libmcrypt and then recompile PHP with mcrypt
support.  See http://www.php.net/mcrypt for instructions on how to
get, compile, and install libmcrypt.  You will need libmcrypt version
2.4.x or newer.  After you have installed libmcrypt, recompile PHP
with this flag: "--with-mcrypt".

Once you have decided which method you'll be using, the setting that
you will change is OTP_CRYPTO_ALGORITHM in the "apache.conf" file,
or $otp_crypto_algorithm in the plugin configuration file (NOT
RECOMMENDED!).  If using the built-in rc4 algorithm, you need to
specify "rc4_builtin".  If using the stronger mcrypt alternative,
you can choose any symmetric algorythm that supports ECB encryption
mode.  For the list of available algorythms, see your libmcrypt
documentation.  You'll typically be able to choose from at least
"blowfish", but you can and are encouraged to change it to some other
strong algorythm to make it even harder to brute-force the passwords.
Possible choices may include "twofish", "tripledes", "gost", "serpent"
and others.



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

  * If you have problems making the apache.conf file settings
    visible to this plugin, check the path used in the
    <Directory> line.  Sometimes symlinked directories can
    cause confusion - try using the symlink name instead of
    the real path.  Always restart the web server after making
    changes to this file.

  * If changes to the configuration file don't seem to be
    having any effect, ensure that you are editing the correct
    configuration file.  If one is located in the main SquirrelMail
    config directory (named "config_otp.php"), it will always be
    used.  Otherwise, "config.php" in the otp plugin directory will
    be used.

  * Likewise, if you have (as recommended) set your cryptographic
    hash phrase and algorithm in your web server's configuration
    instead of using the values in the plugin's PHP configuration
    file, the latter values will be ignored, no matter what changes
    you make to them.



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.



TODO
====
  
  * Allow users to define a sub-set of the features they want
    removed when logged in with a OTP - probably overkill

  * Define different levels of feature sets that get locked out
    (which means different sets/levels of OTPs are needed...
    definitely overkill)

  * Allow users to download the current OTP list, possibly as
    in comma-separated-values format or maybe as a PDF file, etc.

  * Allow users to control the OTP prefix themselves?  Is this
    secure?

  * Ideas?



Change Log
==========
  
  v1.0  2009/01/01  Paul Lesniewski <paul@squirrelmail.org>
    * Initial release.  Thanks to Florian Fink for initial inspiration.



