Preliminary version of the CRAM-MD5, DIGEST-MD5 and SSL documentation.

[squirrelmail.git] / doc / authentication.txt

diff --git a/doc/authentication.txt b/doc/authentication.txt
new file mode 100644 (file)
index 0000000..73d1ed6
--- /dev/null
+++ b/doc/authentication.txt
@@ -0,0 +1,70 @@
+**********************************************
+IMAP AND SMTP AUTHENTICATION WITH SQUIRRELMAIL
+Preliminary documentation - 20 Nov 2002
+Chris Hilts chilts@birdbrained.org
+**********************************************
+
+Prior to SquirrelMail 1.3.3, only plaintext logins for IMAP and SMTP were
+supported.  With the release of SquirrelMail 1.3.3, support for the
+CRAM-MD5 and DIGEST-MD5 auth mechanisms has been added.  TLS support has
+also been added.  It is possible to use different methods for both IMAP and
+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.
+
+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.)
+
+TLS
+* SquirrelMail 1.3.3 or higher
+* PHP 4.3.0 or higher
+* 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) 
+
+CONFIGURATION
+-------------
+
+All configuration is done using conf.pl, under main menu option #2.
+
+KNOWN ISSUES
+------------
+
+DIGEST-MD5 has three different methods of operation. (qop options "auth",
+"auth-int" and "auth-conf").  This implementation currently supports "auth"
+only.  Work is being done to add the other two modes.
+
+DIGEST-MD5 _may_ fail when authenticating with servers that supply more
+than one "realm".  I have no servers of this type to test on, so if you do
+and it fails, let me know!  (A big help would be for you to telnet to your
+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]
+
+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]
+
+[End]