config.php was not loaded before plugin.php, but that's needed to make
[squirrelmail.git] / doc / authentication.txt
CommitLineData
03814228 1**********************************************
2IMAP AND SMTP AUTHENTICATION WITH SQUIRRELMAIL
2f854f5f 3$Id$
4Chris Hilts tassium@squirrelmail.org
03814228 5**********************************************
6
7Prior to SquirrelMail 1.3.3, only plaintext logins for IMAP and SMTP were
8supported. With the release of SquirrelMail 1.3.3, support for the
9CRAM-MD5 and DIGEST-MD5 auth mechanisms has been added. TLS support has
10also been added. It is possible to use different methods for both IMAP and
11SMTP. TLS is able to be enabled on a per-service basis as well.
12Unless the administrator changes the authentication methods, SquirrelMail
13will default to the "classic" plaintext methods, without TLS.
14
a8855d9c 15Note: There is no point in using TLS if your IMAP server is localhost. You need
16root to sniff the loopback interface, and if you don't trust root, or an attacker
17already has root, the game is over. You've got a lot more to worry about beyond
18having the loopback interface sniffed.
19
03814228 20REQUIREMENTS
21------------
22
23CRAM/DIGEST-MD5
24* SquirrelMail 1.3.3 or higher
639c7164 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 **
03814228 28
29TLS
30* SquirrelMail 1.3.3 or higher
a8855d9c 31* PHP 4.3.0 or higher (Check Release Notes for PHP 4.3.x information)
03814228 32* The "STARTTLS" command is NOT supported. The server you wish to use TLS
33 on must have a dedicated port listening for TLS connections. (ie. port
e50f5ac2 34 993 for IMAP, 465 for SMTP)
ad82f7c1 35* If you use PHP 4.3.x, OpenSSL support must be compiled staticly. See
36 PHP bug #29934 (http://bugs.php.net/bug.php?id=29934)
03814228 37
38CONFIGURATION
39-------------
40
41All configuration is done using conf.pl, under main menu option #2.
42
1c6d997a 43conf.pl can now attempt to detect which mechanisms your servers support.
44You must have set the host and port before attempting to detect, or you
45may get inaccurate results, or a long wait while the connection times out.
46
47If you get results that you know are wrong when you use auto-detection, I
48need to know about it. Please send me the results you got, the results you
49expected, and server type, name, and version (eg. "imap, Cyrus, v2.1.9").
50
03814228 51KNOWN ISSUES
52------------
53
54DIGEST-MD5 has three different methods of operation. (qop options "auth",
55"auth-int" and "auth-conf"). This implementation currently supports "auth"
56only. Work is being done to add the other two modes.
57
58DIGEST-MD5 _may_ fail when authenticating with servers that supply more
59than one "realm". I have no servers of this type to test on, so if you do
60and it fails, let me know! (A big help would be for you to telnet to your
61server, start a DIGEST-MD5 auth session, and include the challenge from the
62server in your bug report.)
63
64To get the challenge with IMAP:
e50f5ac2 65 telnet <your server> imap
66 [server says hello]
67 A01 AUTHENTICATE DIGEST-MD5
68 <copy the gobbledygook that the server sends - this is what I need>
69 *
70 [server says auth aborted]
71 A02 LOGOUT
72 [server says goodbye, closes connection]
03814228 73
74To get the challenge with SMTP:
e50f5ac2 75 telnet <your server> smtp
76 [server sends some sort of "hello" banner]
77 EHLO myhostname
78 [server will probably list a bunch of capabilities]
79 AUTH DIGEST-MD5
80 <copy the gobbledygook that the server sends - this is what I need>
81 *
82 [server says auth aborted]
83 QUIT
84 [server says bye, closes connection]
03814228 85
c475d271 86
87OPTIONAL SMTP AUTH CONFIGURATION
88--------------------------------
89
90If you need all users to send mail via an upstream SMTP provider
91(your ISP, for example), and that ISP requires authentication,
92there are two variables that can be added to config_local.php
93that will specify a sitewide SMTP username and password.
94
e50f5ac2 95Set up SMTP authentication to the remote server according to the
96instructions above, then add the following to config_local.php,
c475d271 97replacing <smtp_user> and <smtp_pass> with the username and password
98you'd like to use for the entire site:
99
e50f5ac2 100 $smtp_sitewide_user = '<smtp_user>';
101 $smtp_sitewide_pass = '<smtp_pass>';
c475d271 102
103These values will be used to connect to the SMTP server as long
104as the authentication mechanism is something besides 'none', i.e.
105'login','plain','cram-md5', or 'digest-md5'.
106
107
03814228 108[End]