Use squirrelmail.org
[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
a15f9d93 7Prior to SquirrelMail 1.4.0, only plaintext logins for IMAP and SMTP were
8supported. With the release of SquirrelMail 1.4.0, support for the
03814228 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
a15f9d93 24* SquirrelMail 1.4.0 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 **
a15f9d93 28* Digest-MD5 authentication needs PHP XML extension.
03814228 29
30TLS
a15f9d93 31* SquirrelMail 1.4.0 or higher
a8855d9c 32* PHP 4.3.0 or higher (Check Release Notes for PHP 4.3.x information)
a15f9d93 33* The server you wish to use TLS on must have a dedicated port listening for
34 TLS connections. (ie. port 993 for IMAP, 465 for SMTP). See STARTTLS
35 requirements, if you want to use IMAP or SMTP STARTTLS extension.
ad82f7c1 36* If you use PHP 4.3.x, OpenSSL support must be compiled staticly. See
37 PHP bug #29934 (http://bugs.php.net/bug.php?id=29934)
03814228 38
a15f9d93 39STARTTLS
40* SquirrelMail 1.5.1 or higher
41* PHP 5.1.0rc1 or higher (stream_socket_enable_crypto() function)
42* Server with STARTTLS extension support
43
03814228 44CONFIGURATION
45-------------
46
47All configuration is done using conf.pl, under main menu option #2.
48
1c6d997a 49conf.pl can now attempt to detect which mechanisms your servers support.
50You must have set the host and port before attempting to detect, or you
51may get inaccurate results, or a long wait while the connection times out.
52
a15f9d93 53If you get results that you know are wrong when you use auto-detection, send
54information about it to SquirrelMail developers. Provide the results you got,
55the results you expected, and server type, name, and version (eg. "imap,
56Cyrus, v2.1.9").
1c6d997a 57
03814228 58KNOWN ISSUES
59------------
60
61DIGEST-MD5 has three different methods of operation. (qop options "auth",
62"auth-int" and "auth-conf"). This implementation currently supports "auth"
63only. Work is being done to add the other two modes.
64
65DIGEST-MD5 _may_ fail when authenticating with servers that supply more
66than one "realm". I have no servers of this type to test on, so if you do
67and it fails, let me know! (A big help would be for you to telnet to your
68server, start a DIGEST-MD5 auth session, and include the challenge from the
69server in your bug report.)
70
71To get the challenge with IMAP:
e50f5ac2 72 telnet <your server> imap
73 [server says hello]
74 A01 AUTHENTICATE DIGEST-MD5
75 <copy the gobbledygook that the server sends - this is what I need>
76 *
77 [server says auth aborted]
78 A02 LOGOUT
79 [server says goodbye, closes connection]
03814228 80
81To get the challenge with SMTP:
e50f5ac2 82 telnet <your server> smtp
83 [server sends some sort of "hello" banner]
84 EHLO myhostname
85 [server will probably list a bunch of capabilities]
86 AUTH DIGEST-MD5
87 <copy the gobbledygook that the server sends - this is what I need>
88 *
89 [server says auth aborted]
90 QUIT
91 [server says bye, closes connection]
03814228 92
c475d271 93
94OPTIONAL SMTP AUTH CONFIGURATION
95--------------------------------
96
029d1fc2 97In SMTP authentication SquirrelMail uses user's login name and password. If you
98need all users to send mail via an upstream SMTP provider (your ISP, for
99example), and that ISP requires authentication, you can configure custom
100username and password. $smtp_sitewide_user configuration variable stores custom
101username used during SMTP authentication. $smtp_sitewide_pass stores custom
102password that is used during SMTP authentication, if $smtp_sitewide_user
103variable is not empty.
104
105SquirrelMail 1.5.0 and 1.5.1 stored these configuration variables in
106config_local.php. Newer SquirrelMail versions allow to configure them in conf.pl
107configuration utility.
108
109These configuration variables will be used to connect to the SMTP server as long
110as the authentication mechanism is something besides 'none', i.e. 'login',
111'plain', 'cram-md5', or 'digest-md5'.
c475d271 112
a15f9d93 113DEBUGGING SSL ERROR MESSAGES
114----------------------------
115
116SquirrelMail disables display of PHP errors in fsockopen() and
117stream_socket_enable_crypto() function calls. These functions use PHP error
118handler to display connection errors and SquirrelMail tries to handle
119errors without displaying debugging information to end user. If you use TLS or
120STARTTLS and get connection errors, try reproducing them in configtest.php
121script or remove @ symbol from fsockopen() and stream_socket_enable_crypto()
122calls in SquirrelMail scripts.
123
124Possible error messages:
125* SSL: Connection reset by peer in some script.
126 Error happened in IMAP server and server dropped connection. It is possible
127 that error is logged in system or imap logs.
128
129* SSL operation failed with code 1. OpenSSL Error messages: error:14094410:SSL
130routines:func(148):reason(1040) in some script.
029d1fc2 131 Error generated by SSL library. Locate numbers listed in 'SSL
a15f9d93 132 routines:func(###):reason(####)' string, find ssl.h file in your OpenSSL
133 sources and locate same numbers listed in '/* Error codes for the SSL
134 functions. */' section. Error define can be self explanatory. If you don't
135 understand it, search for error or that define in your favorite search
136 engine.
137
c475d271 138
03814228 139[End]