copyright update

[squirrelmail.git] / doc / authentication.txt

diff --git a/doc/authentication.txt b/doc/authentication.txt
index 73d1ed69477da359381aad1b8ca63c8817b29594..98e61105635d4f3d703a421ae07db457ce647dd6 100644 (file)
--- a/doc/authentication.txt
+++ b/doc/authentication.txt
@@ -1,7 +1,7 @@
 **********************************************
 IMAP AND SMTP AUTHENTICATION WITH SQUIRRELMAIL
-Preliminary documentation - 20 Nov 2002
-Chris Hilts chilts@birdbrained.org
+$Id$
+Chris Hilts tassium@squirrelmail.org
 **********************************************
 
 Prior to SquirrelMail 1.3.3, only plaintext logins for IMAP and SMTP were
@@ -12,26 +12,42 @@ SMTP. TLS is able to be enabled on a per-service basis as well.
 Unless the administrator changes the authentication methods, SquirrelMail
 will default to the "classic" plaintext methods, without TLS.
 
+Note: There is no point in using TLS if your IMAP server is localhost. You need
+root to sniff the loopback interface, and if you don't trust root, or an attacker
+already has root, the game is over.  You've got a lot more to worry about beyond
+having the loopback interface sniffed.
+
 REQUIREMENTS
 ------------
 
 CRAM/DIGEST-MD5
 * SquirrelMail 1.3.3 or higher
-* The mhash extension for PHP. (Debian users: You're lucky.  Type 'apt-get
-  install php4-mhash' and you're done.)
+* If you have the mhash extension to PHP, it will automatically
+  be used, which may help performance on heavily loaded servers.
+  ** NOTE: mhash is optional and no longer a requirement **
 
 TLS
 * SquirrelMail 1.3.3 or higher
-* PHP 4.3.0 or higher
+* PHP 4.3.0 or higher (Check Release Notes for PHP 4.3.x information)
 * The "STARTTLS" command is NOT supported.  The server you wish to use TLS
   on must have a dedicated port listening for TLS connections. (ie. port
-  993 for IMAP, 465 for SMTP) 
+  993 for IMAP, 465 for SMTP)
+* If you use PHP 4.3.x, OpenSSL support must be compiled staticly. See
+  PHP bug #29934 (http://bugs.php.net/bug.php?id=29934)
 
 CONFIGURATION
 -------------
 
 All configuration is done using conf.pl, under main menu option #2.
 
+conf.pl can now attempt to detect which mechanisms your servers support.
+You must have set the host and port before attempting to detect, or you
+may get inaccurate results, or a long wait while the connection times out.
+
+If you get results that you know are wrong when you use auto-detection, I
+need to know about it. Please send me the results you got, the results you
+expected, and server type, name, and version (eg. "imap, Cyrus, v2.1.9").
+
 KNOWN ISSUES
 ------------
 
@@ -46,25 +62,47 @@ server, start a DIGEST-MD5 auth session, and include the challenge from the
 server in your bug report.)
 
 To get the challenge with IMAP:
-       telnet <your server> imap
-       [server says hello]
-       A01 AUTHENTICATE DIGEST-MD5
-       <copy the gobbledygook that the server sends - this is what I need>
-       *
-       [server says auth aborted]
-       A02 LOGOUT
-       [server says goodbye, closes connection]
+   telnet <your server> imap
+   [server says hello]
+   A01 AUTHENTICATE DIGEST-MD5
+   <copy the gobbledygook that the server sends - this is what I need>
+   *
+   [server says auth aborted]
+   A02 LOGOUT
+   [server says goodbye, closes connection]
 
 To get the challenge with SMTP:
-       telnet <your server> smtp
-       [server sends some sort of "hello" banner]
-       EHLO myhostname
-       [server will probably list a bunch of capabilities]
-       AUTH DIGEST-MD5
-       <copy the gobbledygook that the server sends - this is what I need>
-       *
-       [server says auth aborted]
-       QUIT
-       [server says bye, closes connection]
+   telnet <your server> smtp
+   [server sends some sort of "hello" banner]
+   EHLO myhostname
+   [server will probably list a bunch of capabilities]
+   AUTH DIGEST-MD5
+   <copy the gobbledygook that the server sends - this is what I need>
+   *
+   [server says auth aborted]
+   QUIT
+   [server says bye, closes connection]
+
+
+OPTIONAL SMTP AUTH CONFIGURATION
+--------------------------------
+
+If you need all users to send mail via an upstream SMTP provider
+(your ISP, for example), and that ISP requires authentication,
+there are two variables that can be added to config_local.php
+that will specify a sitewide SMTP username and password.
+
+Set up SMTP authentication to the remote server according to the
+instructions above, then add the following to config_local.php,
+replacing <smtp_user> and <smtp_pass> with the username and password
+you'd like to use for the entire site:
+
+   $smtp_sitewide_user = '<smtp_user>';
+   $smtp_sitewide_pass = '<smtp_pass>';
+
+These values will be used to connect to the SMTP server as long
+as the authentication mechanism is something besides 'none', i.e.
+'login','plain','cram-md5', or 'digest-md5'.
+
 
 [End]