*****************************************
IMAP AND SMTP AUTHENTICATION WITH NASMAIL
*****************************************

NaSMail can use IMAP LOGIN, CRAM-MD5 and DIGEST-MD5 authentication mechanisms.
Connections can be encrypted with TLS or STARTTLS, if PHP installation supports
required encryption functions. It is possible to use different methods for both
IMAP and SMTP. TLS and STARTTLS can be enabled on a per-service basis as well.
Unless the administrator changes the authentication methods, NaSMail 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
* 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 **
* IMAP server must support utf8 charset in Digest MD5 (rfc2831) authentication.
  Currently only single realm authentication is supported.

TLS
* PHP 4.3.0 or higher with OpenSSL support
* 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). See STARTTLS
  requirements, if you want to use IMAP or SMTP STARTTLS extension.
* If you use PHP 4.x, OpenSSL support must be compiled statically. See PHP bug
  #29934 (http://bugs.php.net/bug.php?id=29934)

STARTTLS
* PHP 5.1.0 or higher (stream_socket_enable_crypto() function)
* IMAP or SMTP server with STARTTLS extension support


CONFIGURATION
-------------

All configuration is done using conf.pl, under main menu option #2.

conf.pl can 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. TLS
connections can't be tested. Servers with STARTTLS support might hide supported
authentication methods.


KNOWN ISSUES
------------

DIGEST-MD5 has three different methods of operation. (qop options "auth",
"auth-int" and "auth-conf"). This implementation currently supports "auth"
only.

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]
