Attachment 117819 Details for Bug 176594 – doc in guidexml

doc in guidexml

webmail-otp.xml (text/plain), 15.26 KB, created by Eric Brown on 2007-05-01 09:59:07 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Eric Brown

Created: 2007-05-01 09:59:07 UTC

Size: 15.26 KB

patch

obsolete

><?xml version='1.0' encoding="UTF-8"?>
><!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
>
><guide link="/doc/en/webmail-otp.xml">
><title>One time passwords for your webmail</title>
>
><author title="Author">
>  <mail link="eric.brown@dnbrown.net">Eric Brown</mail>
></author>
>
><abstract>
>This tutorial explains a convenient way to one time passwords setup for
>webmail/IMAP systems that use courier-imap and courier-authlib for
>authentication via PAM.  The techniques mentioned herein only work with systems
>that use non-virtual users for IMAP authentication.
></abstract>
>
>
>
><license/>
>
><version>1.0</version>
><date>2007-04-30</date>
>
><chapter>
><title>Background</title>
><section>
><title>Webmail and security</title>
><body>
>
><p>
>Webmail provides a convenient way to access e-mail from anywhere one the World
>Wide Web where an Internet connection and a browser are available.  However,
>along with the convenience of such a readily available service, some important
>security considerations are often neglected, namely prevention of the theft and
>forgery of authentication information.
></p>
>
><p>
>Some of these issues can be mitigated by ensuring a secure connection between
>the client and the server, that is, using strong encryption and identity
>verification provided by protocols like SSL.  Simply using SSL often provides
>enough security for systems where the client equipment and login locations are
>trusted: where users log in from machines that are not infected by key loggers
>or spyware; where visual eavesdropping and recording is prevented; and where
>their sessions are not otherwise recorded.  That being so, with the profusion
>of viruses and spyware, and the fact that many users may be using untrusted
>machines in untrusted locations frequently, naively assuming that a secure
>connection alone can prevent information theft, is categorically dangerous.
></p>
>
><p>
>Think about it for a moment, have you ever checked your e-mail at an Internet
>cafe and worried about spyware or key loggers? Have you ever had to login while
>a colleague was watching? Can you guarantee that you are the only person that
>knows your email login and password?
></p>
>
></body>
></section>
><section>
><title>Time limited one time passwords can help</title>
><body>
>
><p>
>To be able to freely use webmail on untrusted systems, or in untrusted
>locations without having to be overly concerned with the possible theft of
>authentication information, one good approach is to decrease the usefulness of
>the authentication information once it has been used, namely by using  <e>time
>limited one time passwords</e>.  Functionally, this means that each time a user
>logs into the webmail system, he must use a new password, and that that each
>login session is limited to a short amount of time.  The implication is that
>the login information that can be stolen during a webmail session becomes
>useless after it expires.
></p>
>
></body>
></section>
>
><section>
><title>Some remaining security issues</title>
><body>
>
><p>
>In reality, despite the benefits of using time limited one time passwords,
>there are still some major pitfalls that need mentioned:
></p>
>
><ul>
><li>
>We are not able to use true <e>one time passwords</e> with most IMAP based
>webmail systems, they are just passwords that expire after a defined period of
>time, and cannot be reused.  If concurrent logins by the same user are allowed,
>a quick moving attacker could record the login credentials and simultaneously
>log in and steal information until the password expires.
></li>
><li>
>Even after logging out, due to the time based nature of this method, the
>password is still valid until its lifetime expires.  An attacker could record
>the login credentials and use them until they expire.
></li>
><li>
>The session could still be hijacked by a malicious user with absolute control
>over the client computer.  Furthermore, since most webmail systems will not log
>an active user out until he tries to access a page that requires IMAP, an
>attacker could theoretically make unlimited use of other non-authenticating
>parts of the webmail system unless an absolute session timeout was defined in
>the webmail system.
></li>
><li>
>This method can be time consuming: a list of passwords must be consulted and
>the passwords expire after a short amount of time.  For this reason, most
>administrators will probably want to setup a static password based webmail
>system restricted to <e>secure</e> use to avoid using the one time passwords.
>This could be a system only accessible from a VPN or a local network, or
>perhaps one that is only used from a trusted computer.
></li>
></ul>
>
></body>
></section>
>
></chapter>
><chapter>
><title>Implementation</title>
><section>
><title>Pre-implementation concerns</title>
><body>
>
><p>
>There are a few requirements that the administrator should be aware of before
>implementing this kind of authentication system:
></p>
>
><ul>
><li>
>The one time passwords are managed per user, so for users to be able to use
>this, they must either be able to login to generate/obtain passwords, or have
>the administrator do it for them.
></li>
><li>
>This method only works for real system users, not virtual users
></li>
><li>
>This document assumes the use of courier-imap because it provides an easy way
>to select the pam services it uses per-port.  Other pam-capable IMAP servers
>should also work, but perhaps not with multiple pam services in use
></li>
><li>
>This document assumes the use of SquirrelMail, though most other webmail
>platforms will also work
></li>
><li>
>This document assumes you have your web server setup already, and that you are
>installing web applications to <path>/var/www/localhost</path> by default
></li>
></ul>
>
></body>
></section>
><section>
><title>Step 1: Installing necessary applications</title>
><body>
>
><p>
>First we should install pam_sotp, courier-imap and squirrelmail.  If you do no
>have a hardware random number generator, be sure to use the urandom local use
>flag for the pam_sotp package:
></p>
>
><pre caption="adding a use flag to /etc/portage/package.use">
>sys-libs/pam_sotp    urandom
></pre>
>
><pre caption="installing the applications">
>$ <i>emerge pam_sotp courier-imap squirrelmail</i>
></pre>
>
></body>
></section>
><section>
><title>Step 2: Configuring Courier</title>
><body>
>
><p>
>Next we have to make sure courier-imap is installed properly.  If you already
>have it installed, make sure you have the <c>pam</c> USE flag enabled for
>courier-authlib.  Courier-authlib needs to be using PAM for this method to
>work, take a look at <path>/etc/courier/authlib/authdaemonrc</path> and make
>sure you have <c>authpam</c> in your authmodulelist variable:
></p>
>
><pre caption="editing /etc/couerier/authlib/authdaemonrc">
>authmodulelist="authpam"
></pre>
>
><p>
>Next we need to make sure that the imapd service (or imap-ssl) is configured to
>run an extra IMAP daemon on a separate port (any port above 1024 should
>suffice, we'll use 11143).  If you use plain authentication over an unsecured
>connection, imapd-ssl might be more appropriate; this document will not cover
>the ssl specific configuration steps.
></p>
>
><pre caption="editing /etc/courier-imap/imapd (or imapd-ssl)">
># This will run imapd on port 143 and 11143 on the default interface
>PORT=143,11143
>
># port 143 connections will authenticate with the default pam service
># port 11143 connections will authenticate with the pam_sotp enabled service
>AUTHSERVICE143=imap
>AUTHSERVICE11143=imapotp
></pre>
>
><p>
>Restart the courier-authlib and courier-imap services:
></p>
>
><pre caption="restarting courier-imap and courier-authlib">
>$ <i>/etc/init.d/courier-authlib stop</i>
>$ <i>/etc/init.d/courier-imapd start</i>
></pre>
>
></body>
></section>
><section>
><title>Step 3: Configuring the new PAM service</title>
><body>
>
><p>
>Next the new imapotp pam service mentioned above needs to be created.  Here the
>lifetime of the one time passwords needs to be chosen and placed that value (in
>seconds) in the pw_lifespan variable.  A lifespan of 300 seconds (5 minutes)
>means that when you login to your webmail, you will be logged out after 5
>minutes and be prompted to login again with a new password.
></p>
>
><pre caption="creating /etc/pam.d/imapotp">
>auth       required     pam_nologin.so
>auth       required    pam_sotp.so pw_lifespan=300
>account    required     pam_stack.so service=system-auth
>session    required     pam_stack.so service=system-auth
></pre>
>
><note>
>A value of zero means that the password expires immediately, this does not work
>well for IMAP based webmail systems, but for terminal logins, it would be
>perfect.
></note>
>
></body>
></section>
><section>
><title>Step 4: Configure SquirrelMail</title>
><body>
>
><p>
>Locate your SquirrelMail installation:
></p>
>
><pre caption="locating your SquirrelMail installation">
>$ <i>webapp-config --li -V</i>
></pre>
>
><p>
>If there are no installations for SquirrelMail (assuming version 1.4.9a),
>install it somewhere:
></p>
>
><pre caption="installing an instance of SquirrelMail">
><comment>
>This will install it to /var/www/localhost/htdocs/squirrelmail you may also
>need to further configure your web server
></comment>
>$ <i>webapp-config -I -h localhost -d squirrelmail squirrelmail1.4.9a</i>
></pre>
>
><p>
>If you want to run a separate instance of SquirrelMail; a convenience version
>to handle plain authentication and a secure one to handle pam_sotp
>authentication, install another instance somewhere else:
></p>
>
><pre caption="installing another instance of SquirrelMail">
>$ <i>webapp-config -I -h localhost -d squirrelmail_internal squirrelmail 1.4.9a</i>
></pre>
>
><p>
>Configure your pam_sotp instance of SquirrelMail, pay attention to the
>following variables:
></p>
>
><pre caption="/var/www/localhost/htdocs/squirrelmail/config/config.php">
>// this is the base URL of your SquirrelMail installation
>$config_location_base = 'https://some.ip.or.domain/squirrelmail';
>// this is where you tell it what port to use for imap
>// on the insecure instance of SquirrelMail, you'd just use port 143
>$imapPort = 11143;
>// if you use courier, be sure to set this variable
>$imap_server_type = 'courier';
></pre>
>
><p>
>Depending on your web server, you may need to restart it for the changes to
>take effect:
></p>
>
><pre caption="restarting the web server">
>$ <i>/etc/init.d/lighttpd restart</i>
></pre>
>
></body>
></section>
><section>
><title>Step 5: Configure a user's one time passwords</title>
><body>
>
><p>
>Next, a set of one time passwords must be generated for one of your users.  The
><c>otppasswd</c> utility included with pam_sotp is used for this, and it
>presents some important options that should be considered:
></p>
>
><ul>
><li>
>Passwords can optionally include a prefix, this is important to include so that
>if the list of passwords is stolen, the attacker would still need to know the
>prefix before he could log in.  The prefix is simply a short password that
>precedes all passwords generated by otppasswd, each password will use the same
>prefix.  Obviously, for security reasons, you would not want to keep the prefix
>listed in the same place as your one time passwords (users can simply remember
>it).
></li>
><li>
>You may recall that a password lifetime was already selected in the PAM service
>configuration file.  The lifetime of the passwords can also be defined here,
>pam_sotp will simply use the lesser of the two values defined.
></li>
><li>
><c>otppasswd</c> allows us to configure the characters used by the passwords,
>as well as the length of the passwords.  This document will assume that a
>default length of 6 with a character set including [0-9] and [A-F] for
>convenience.  If you are very concerned with a brute force attack, you may want
>to either: increase the length of the passwords and the breadth of the
>character set; or take other measures to limit the amount of tries a user can
>make.
></li>
><li>
>The entire password set can be set to expire in a chosen number of days.
>Although this option is not used here, it is probably wise to make use of it
>once comfortable with the system.
></li>
></ul>
>
><pre caption="generating passwords">
><comment>
>Generate 20 passwords, each with a length of 6, prefixed by foobar (won't be
>output) expiring in 300 seconds, with a character set of [A-F0-9]
></comment>
>$ <i>otppasswd -n 20 -l 6 -c 0123456789ABCDEF -p foobar</i>
></pre>
>
><note>
>If after a minute or two there is no output, it might be trying to use
><path>/dev/random</path> instead of <path>/dev/urandom</path>, and
><path>/dev/random</path> might not be working.  In this case, kill the
>processes, rebuild it with the <e>urandom</e> use flag and try again.
></note>
>
><p>
>A list of passwords will be generated.  The list is numbered by default, and it
>does not include the selected prefix in the output.  Write the list of
>passwords down on a piece of paper.  Do not write the prefix on this piece of
>paper, just remember it.
></p>
>
></body>
></section>
><section>
><title>Step 6: Testing the installation</title>
><body>
>
><p>
>The best way to test this system, is to simply open up a browser and try to
>login as the user you just configured one time passwords for.  For instance, if
>you are logging in with a prefix password of <e>foobar</e>, and the first
>password in your list is <e>ABC123</e>, you would log in with the password
><e>foobarABC123</e>.
></p>
>
><p>
>If it works on the first try, congratulations!  If not, there are several kinds
>of problems you might want to consider, though the precise solutions are beyond
>this document:
></p>
>
><ul>
><li>
>Web server or SquirrelMail problems: Do you get the login screen for
>SquirrelMail when you go to https://my.domain.com/squirrelmail? Are there any
>unusual messages in your web server's logs?  Is your web server logging access
>so that you can solve this class of problems? Are there errors in your
>SquirrelMail configuration file?
></li>
><li>
>Courier-imap and PAM problems: Can you see if SquirrelMail is attempting to
>login to your IMAP server? Does /var/log/messages show any login attempts for
>IMAP?  Are there failed attempts from authdaemond that mention pam_sotp, or is
>it using another PAM module?  Is /etc/courier-imap/imapd configured to use the
>imapotp pam service?  Is the imapotp PAM service using pam_sotp?  Is there a
>more fundamental problem with courier's login configuration?
></li>
><li>
>Connectivity problems: If there are no records showing authentication attempts
>on IMAP, are you running a firewall that prevents access to the new imapd port?
>Is your web server allowed to make connections, or is it restricted by access
>controls (SELinux, Grsec)?
></li>
><li>
>Do you have PAM authentication enabled for courier-authlib?  Was it even built
>with the PAM USE flag?
></li>
><li>
>If you can attempt to login, but it fails, does configuring SquirrelMail to use
>the plain IMAP port work with the user's system password?
></li>
></ul>
>
></body>
></section>
><section>
><title>Important resources:</title>
><body>
>
><p>
>This document touches on a wide section of the system, there are some important
>documents that should be consulted if there are any problems:
></p>
>
><ul>
><li>
><c>man pam</c> has a good summary of how it works, you should be familiar with
>it anyway
></li>
><li>
>documents in <path>/usr/share/docs/pam_sotp-*</path> provide a great
>introduction to this easy to use, and extremely useful PAM module
></li>
><li>
>The GDP Apache Troubleshooting guide might be useful:
><uri>http://www.gentoo.org/doc/en/apache-troubleshooting.xml</uri>
></li>
><li>
>Courier is probably the hardest part to get configured correctly, there are
>some useful docs in <path>/usr/share/docs/courier-*</path>
></li>
></ul>
>
>
></body>
></section>
></chapter>
></guide>

Actions: View

Attachments on bug 176594: 117819