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

[squirrelmail.git] / doc / authentication.txt

**********************************************
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]