doc/authentication.txt

   1 **********************************************
   2 IMAP AND SMTP AUTHENTICATION WITH SQUIRRELMAIL
   3 $Id$
   4 Chris Hilts tassium@squirrelmail.org
   5 **********************************************
   6
   7 Prior to SquirrelMail 1.4.0, only plaintext logins for IMAP and SMTP were
   8 supported.  With the release of SquirrelMail 1.4.0, support for the
   9 CRAM-MD5 and DIGEST-MD5 auth mechanisms has been added.  TLS support has
  10 also been added.  It is possible to use different methods for both IMAP and
  11 SMTP. TLS is able to be enabled on a per-service basis as well.
  12 Unless the administrator changes the authentication methods, SquirrelMail
  13 will default to the "classic" plaintext methods, without TLS.
  14
  15 Note: There is no point in using TLS if your IMAP server is localhost. You need
  16 root to sniff the loopback interface, and if you don't trust root, or an attacker
  17 already has root, the game is over.  You've got a lot more to worry about beyond
  18 having the loopback interface sniffed.
  19
  20 REQUIREMENTS
  21 ------------
  22
  23 CRAM/DIGEST-MD5
  24 * SquirrelMail 1.4.0 or higher
  25 * If you have the mhash extension to PHP, it will automatically
  26   be used, which may help performance on heavily loaded servers.
  27   ** NOTE: mhash is optional and no longer a requirement **
  28 * Digest-MD5 authentication needs PHP XML extension.
  29
  30 TLS
  31 * SquirrelMail 1.4.0 or higher
  32 * PHP 4.3.0 or higher (Check Release Notes for PHP 4.3.x information)
  33 * The server you wish to use TLS on must have a dedicated port listening for
  34   TLS connections. (ie. port 993 for IMAP, 465 for SMTP). See STARTTLS
  35   requirements, if you want to use IMAP or SMTP STARTTLS extension.
  36 * If you use PHP 4.3.x, OpenSSL support must be compiled staticly. See
  37   PHP bug #29934 (http://bugs.php.net/bug.php?id=29934)
  38
  39 STARTTLS
  40 * SquirrelMail 1.5.1 or higher
  41 * PHP 5.1.0rc1 or higher (stream_socket_enable_crypto() function)
  42 * Server with STARTTLS extension support
  43
  44 CONFIGURATION
  45 -------------
  46
  47 All configuration is done using conf.pl, under main menu option #2.
  48
  49 conf.pl can now attempt to detect which mechanisms your servers support.
  50 You must have set the host and port before attempting to detect, or you
  51 may get inaccurate results, or a long wait while the connection times out.
  52
  53 If you get results that you know are wrong when you use auto-detection, send
  54 information about it to SquirrelMail developers. Provide the results you got,
  55 the results you expected, and server type, name, and version (eg. "imap,
  56 Cyrus, v2.1.9").
  57
  58 KNOWN ISSUES
  59 ------------
  60
  61 DIGEST-MD5 has three different methods of operation. (qop options "auth",
  62 "auth-int" and "auth-conf").  This implementation currently supports "auth"
  63 only.  Work is being done to add the other two modes.
  64
  65 DIGEST-MD5 _may_ fail when authenticating with servers that supply more
  66 than one "realm".  I have no servers of this type to test on, so if you do
  67 and it fails, let me know!  (A big help would be for you to telnet to your
  68 server, start a DIGEST-MD5 auth session, and include the challenge from the
  69 server in your bug report.)
  70
  71 To get the challenge with IMAP:
  72    telnet <your server> imap
  73    [server says hello]
  74    A01 AUTHENTICATE DIGEST-MD5
  75    <copy the gobbledygook that the server sends - this is what I need>
  76    *
  77    [server says auth aborted]
  78    A02 LOGOUT
  79    [server says goodbye, closes connection]
  80
  81 To get the challenge with SMTP:
  82    telnet <your server> smtp
  83    [server sends some sort of "hello" banner]
  84    EHLO myhostname
  85    [server will probably list a bunch of capabilities]
  86    AUTH DIGEST-MD5
  87    <copy the gobbledygook that the server sends - this is what I need>
  88    *
  89    [server says auth aborted]
  90    QUIT
  91    [server says bye, closes connection]
  92
  93
  94 OPTIONAL SMTP AUTH CONFIGURATION
  95 --------------------------------
  96
  97 In SMTP authentication SquirrelMail uses user's login name and password. If you
  98 need all users to send mail via an upstream SMTP provider (your ISP, for
  99 example), and that ISP requires authentication, you can configure custom
 100 username and password. $smtp_sitewide_user configuration variable stores custom
 101 username used during SMTP authentication. $smtp_sitewide_pass stores custom
 102 password that is used during SMTP authentication, if $smtp_sitewide_user
 103 variable is not empty.
 104
 105 SquirrelMail 1.5.0 and 1.5.1 stored these configuration variables in
 106 config_local.php. Newer SquirrelMail versions allow to configure them in conf.pl
 107 configuration utility.
 108
 109 These configuration variables will be used to connect to the SMTP server as long
 110 as the authentication mechanism is something besides 'none', i.e. 'login',
 111 'plain', 'cram-md5', or 'digest-md5'.
 112
 113 DEBUGGING SSL ERROR MESSAGES
 114 ----------------------------
 115
 116 SquirrelMail disables display of PHP errors in fsockopen() and
 117 stream_socket_enable_crypto() function calls. These functions use PHP error
 118 handler to display connection errors and SquirrelMail tries to handle
 119 errors without displaying debugging information to end user. If you use TLS or
 120 STARTTLS and get connection errors, try reproducing them in configtest.php
 121 script or remove @ symbol from fsockopen() and stream_socket_enable_crypto()
 122 calls in SquirrelMail scripts.
 123
 124 Possible error messages:
 125 * SSL: Connection reset by peer in some script.
 126   Error happened in IMAP server and server dropped connection. It is possible
 127   that error is logged in system or imap logs.
 128
 129 * SSL operation failed with code 1. OpenSSL Error messages: error:14094410:SSL
 130 routines:func(148):reason(1040) in some script.
 131   Error generated by SSL library. Locate numbers listed in 'SSL
 132   routines:func(###):reason(####)' string, find ssl.h file in your OpenSSL
 133   sources and locate same numbers listed in '/* Error codes for the SSL
 134   functions. */' section. Error define can be self explanatory. If you don't
 135   understand it, search for error or that define in your favorite search
 136   engine.
 137
 138
 139 [End]