GSS_S_PROMPTING_NEEDED is a bit
[cyrus-sasl.git] / doc / sysadmin.html
1 <HTML><HEAD>
2 <title>Cyrus SASL for System Administrators</title>
3 <!-- $Id: sysadmin.html,v 1.50 2005/02/16 20:52:05 shadow Exp $ -->
4 </HEAD>
5 <BODY>
6 <H1>Cyrus SASL for System Administrators</H1>
7
8 This document covers configuring SASL for system administrators,
9 specifically those administrators who are installing a server that
10 uses the Cyrus SASL library.  You may want to read
11 <a href=components.html>this document</a> which presents an
12 overview of the major components of the Cyrus SASL distribution
13 and describes how they interact, as well as <a href=install.html>
14 the installation guide</a>.
15
16 <h2><A NAME="saslintro">What SASL is</A></h2>
17
18 SASL, the Simple Authentication and Security Layer, is a generic
19 mechanism for protocols to accomplish authentication.  Since protocols
20 (such as SMTP or IMAP) use SASL, it is a natural place for code
21 sharing between applications.  Some notable applications that use the
22 Cyrus SASL library include <a
23 href="http://www.sendmail.org">Sendmail</a>,
24 <a href="http://web.asg.cmu.edu/cyrus">Cyrus imapd</a>,
25 and <a href="http://www.openldap.org">OpenLDAP</a>.
26
27 <p> Applications use the SASL library to tell them how to accomplish
28 the SASL protocol exchange, and what the results were.
29
30 <p> SASL is only a framework: specific SASL mechanisms govern the
31 exact protocol exchange.  If there are n protocols and m different
32 ways of authenticating, SASL attempts to make it so only n plus m
33 different specifications need be written instead of n times m
34 different specifications.  With the Cyrus SASL library, the mechanisms
35 need only be written once, and they'll work with all servers that use
36 it.
37
38 <h3><a name="authid">Authentication and authorization identifiers</a></h3>
39
40 An important concept to become familiar with is the difference between
41 an "authorization identifier" and an "authentication identifier".
42
43 <DL compact>
44 <DT>userid (user id, authorization id)<dd> The userid is the
45 identifier an application uses to check allowable options.  On my Unix
46 system, the user "<tt>bovik</tt>" (the account of Harry Q. Bovik) is
47 allowed to write to "<tt>/home/bovik</tt>" and its subdirectories but
48 not to "<tt>/etc</tt>".
49
50 <DT>authid (authentication id)<dd> The authentication identifier is
51 the identifier that is being checked.  "bovik"'s password might be
52 "qqqq", and the system will authenticate anyone who knows "qqqq" as
53 "bovik".  However, it's possible to authenticate as one user but
54 <b>act as</b> another user.  For instance, Harry might be away on
55 vacation and assign one of his graduate students, Jane, to read his
56 mail.  He might then allow Jane to act as him merely by supplying her
57 password and her id as authentication but requesting authorization as
58 "bovik". So Jane might log in with an authentication identifier of
59 "jane" and an authorization id of "bovik" and her own (Jane's)
60 password.
61 </DL>
62
63 <p>Applications can set their own proxy policies; by default, the SASL
64 library will only allow the same user to act for another (that is,
65 userid must equal authid).  See your application's documentation for
66 details about changing the default proxy/authorization policies.
67
68 <h3><a name="realms">Realms</a></h3>
69
70 The Cyrus SASL library supports the concept of "realms".  A realm is
71 an abstract set of users and certain mechanisms authenticate users in
72 a certain realm.
73
74 <p>In the simplest case, a single server on a single machine, the
75 realm might be the fully-qualified domain name of the server.  If the
76 applications don't specify a realm to SASL, most mechanisms will
77 default to this.
78
79 <p> If a site wishes to share passwords between multiple machines, it
80 might choose it's authentication realm as a domain name, such as
81 "CMU.EDU".  On the other hand, in order to prevent the entire site's
82 security from being compromised when one machine is compromised, each
83 server could have it's own realm. Certain mechanisms force the user
84 (client side) to manually configure what realm they're in, making it
85 harder for users to authenticate.
86
87 <p>A single site might support multiple different realms.  This can
88 confuse applications that weren't written in anticipation of this; make
89 sure your application can support it before adding users from different
90 realms into your databases.
91
92 <p>To add users of different realms to sasldb, you can use the
93 <tt>-u</tt> option to saslpasswd2.  The SQL plugin has a way of
94 integrating the realm name into the query string with the '%r' macro.
95
96 <p>The Kerberos mechanisms treat the SASL realm as the Kerberos
97 realm.  Thus, the realm for Kerberos mechanisms defaults to the
98 default Kerberos realm on the server.  They may support cross-realm
99 authentication; check your application on how it deals with this.
100
101 <p>Realms will be passed to saslauthd as part of the saslauthd protocol,
102 however the way each saslauthd module deals with the situation is
103 different (for example, the LDAP plugin allows you to use the realm
104 to query the server, while the rimap and PAM plugins ignore it entirely).
105
106 <p>Realms are represented in a username string by any text followinhg
107 the '@' sign.  So, usernames like rjs3@ANDREW.CMU.EDU, is user 'rjs3'
108 in the realm 'ANDREW.CMU.EDU'.  If no realm is provided, the server's
109 FQDN is assumed (likewise when specifying a realm for saslpasswd2).
110
111 <h2><a name="saslhow">How SASL works</a></h2>
112
113 How SASL works is governed by what mechanism the client and server 
114 choose to use and the exact implementation of that mechanism.  This
115 section describes the way these mechanisms act in the Cyrus SASL
116 implementation.
117
118 <h3>The PLAIN mechanism, <tt>sasl_checkpass()</tt>, and plaintext
119 passwords</h3>
120
121 The PLAIN mechanism is not a secure method of authentication by
122 itself.  It is intended for connections that are being encrypted by
123 another level.  (For example, the IMAP command "STARTTLS" creates an
124 encrypted connection over which PLAIN might be used.) The PLAIN
125 mechanism works by transmitting a userid, an authentication id, and a
126 password to the server, and the server then determines whether that is
127 an allowable triple.
128
129 <p>The principal concern for system administrators is how the
130 authentication identifier and password are verified.  The Cyrus SASL
131 library is flexible in this regard:
132
133 <DL>
134 <dt><i>auxprop</i> 
135 <dd> checks passwords agains the <tt>userPassword</tt> attribute
136 supplied by an auxiliary property plugin.  For example, SASL ships
137 with a sasldb auxiliary property plugin, that can be used to
138 authenticate against the passwords stored in <tt>/etc/sasldb2</tt>.
139 Since other mechanisms also use this database for passwords, using
140 this method will allow SASL to provide a uniform password database to
141 a large number of mechanisms.
142
143 <dt><i>saslauthd</i>
144
145 <dd> contacts the <tt>saslauthd</tt> daemon to to check passwords
146 using a variety of mechanisms.  More information about the various invocations
147 of saslauthd can be can be found in <tt>saslauthd(8)</tt>.  Generally you
148 want something like <tt>saslauthd -a pam</tt>.  If plaintext authentications
149 seem to be taking some time under load, increasing the value of the <tt>-n</tt>
150 parameter can help.<p>
151
152 Saslauthd keeps its named socket in "/var/state/saslauthd" by default.
153 This can be overridden by specifying an alternate value to
154 --with-saslauthd=/foo/bar at compile time, or by passing the -m
155 parameter to saslauthd (along with setting the saslauthd_path SASL
156 option).  Whatever directory this is, it must exist in order for
157 saslauthd to function.<p>
158
159 Once you configure (and start) <tt>saslauthd</tt>, there is a
160 <tt>testsaslauthd</tt> program that can be built with <tt>make
161 testsaslauthd</tt> in the <tt>saslauthd</tt> subdirectory of the
162 source.  This can be used to check that that the <tt>saslauthd</tt>
163 daemon is installed and running properly.  An invocation like
164 <tt>testsaslauthd -u rjs3 -p 1234</tt> with appropriate values for the
165 username and password should do the trick.<p>
166
167 If you are using the PAM method to verify passwords with saslauthd, keep in
168 mind that your PAM configuration will need to be configured for each service
169 name that is using saslauthd for authentication. Common service names
170 are &quot;imap&quot;, &quot;sieve&quot;, and &quot;smtp&quot;.
171
172 <dt><i>Courier-IMAP authdaemond</i>
173
174 <dd> contacts Courier-IMAP's <tt>authdaemond</tt> daemon to check passwords.
175 This daemon is simliar in functionality to <tt>saslauthd</tt>, and is shipped
176 separately with the <a href="http://www.courier-mta.org">Courier</a> mail server.
177
178 <p>Note: this feature is <b>not</b> compiled in the library by default, and its 
179 provided for sites with custom/special requirements only (because the
180 internal authentication protocol its not documented anywhere so it could
181 change at any time).  We have tested against the authdaemond included with
182 Courier-IMAP 2.2.1.
183
184 <p>To enable <tt>authdaemond</tt> support, pass <tt>--with-authdaemon</tt> to the 
185 configuration script, set pwcheck_method to ``authdaemond'' and point 
186 authdaemon_path to <tt>authdaemond</tt>'s unix socket. Optionally, you can
187 specify --with-authdaemond=PATH to the configure script so that
188 authdaemond_path points to a default, static, location.
189
190 <dt><i>pwcheck</i>
191
192 <dd> checks passwords with the use of a separate,
193   helper daemon.  This feature is for backwards-compatibility
194   only. New installations should use saslauthd.<p>
195
196 <dt><i>write your own</i>
197 <dd> Last, but not least, the most flexible method of authentication
198 for PLAIN is to write your own.  If you do so, any application that
199 calls the "<tt>sasl_checkpass()</tt>" routine or uses PLAIN will
200 invoke your code.  The easiest place to modify the plaintext
201 authentication routines is to modify the routine
202 "<tt>_sasl_checkpass()</tt>" in the file <tt>lib/server.c</tt> to
203 support a new method, and to add that method to
204 <tt>lib/checkpw.c</tt>.  Be sure to add a prototype in
205 <tt>lib/saslint.h</tt>!
206
207 <p>However, the more flexible and preferred method of
208 adding a routine is to create a new saslauthd mechanism.<p> </dl>
209
210 <p>The LOGIN mechanism (not to be confused with IMAP4's LOGIN command)
211 is an undocumented, unsupported mechanism.  It's included in the Cyrus
212 SASL distribution for the sake of SMTP servers that might want to
213 interoperate with old clients.  Do not enable this mechanism unless
214 you know you're going to need it.  When enabled, it verifies passwords
215 the same way the PLAIN mechanism does.
216
217 <h3>Shared secrets mechanisms</h3>
218
219 The Cyrus SASL library also supports some "shared secret"
220 authentication methods: CRAM-MD5 and its successor DIGEST-MD5.  These
221 methods rely on the client and the server sharing a "secret", usually
222 a password.  The server generates a challenge and the client a
223 response proving that it knows the shared secret.  This is much more
224 secure than simply sending the secret over the wire proving that the
225 client knows it.
226
227 <p>There's a downside: in order to verify such responses, the
228 server must keep passwords or password equivalents in a database;
229 if this database is compromised, it is the same as if all the
230 passwords for the realm are compromised.
231
232 <p>Put another way, <i>you cannot use saslauthd with these methods</i>.  
233 If you do not wish to advertise these methods for that reason (i.e. you
234 are only using saslauthd for password verification), then either remove
235 the non-plaintext plugins (those other than login and plain) from the
236 plugin directory, or use the <tt>mech_list</tt> option to disable them.
237
238 <p>For simplicity sake, the Cyrus SASL library stores plaintext
239 passwords only in the <tt>/etc/sasldb2</tt> database.  These passwords
240 are then shared among all mechanisms which choose to use it.
241 Depending on the exact database method
242 used (gdbm, ndbm, or db) the file may have different suffixes or may
243 even have two different files ("<tt>sasldb.dir</tt>" and
244 "<tt>sasldb.pag</tt>").  It is also possible for a server to define
245 it's own way of storing authentication secrets.  Currently, no
246 application is known to do this.
247
248 <p>The principle problem for a system administrator is to make sure that
249 sasldb is properly protected. Only the servers that need to read it to
250 verify passwords should be able to.  If there are any normal shell
251 users on the system, they must not be able to read it.
252
253 <p>This point is important, so we will repeat it: <b>sasldb stores the
254 plaintext versions of all of its passwords. If it is compromised so
255 are all of the passwords that it stores</b>.
256
257 <p>Managing password changes is outside the scope of the library.
258 However, system administrators should probably make a way of letting
259 user's change their passwords available to users.  The
260 "<tt>saslpasswd2</tt>" utility is provided to change the secrets in
261 sasldb.  It does not affect PAM, <tt>/etc/passwd</tt>, or any other
262 standard system library; it only affects secrets stored in sasldb.
263
264 <p>Finally, system administrators should think if they want to enable
265 "auto_transition".  If set, the library will automatically create
266 secrets in sasldb when a user uses PLAIN to successfully authenticate.
267 However, this means that the individual servers, such as imapd, need
268 read/write access to sasldb, not just read access.  By default,
269 "auto_transition" is set to false; set it to true to enable.  (There's
270 no point in enabling this option if "pwcheck_method" is "auxprop",
271 and the sasldb plugin is installed, since you'll be transitioning from
272 a plaintext store to a plaintext store)
273
274 <h3>Kerberos mechanisms</h3>
275
276 The Cyrus SASL library also comes with two mechanisms that make use of
277 Kerberos: KERBEROS_V4, which should be able to use any Kerberos v4
278 implementation, and GSSAPI (tested against MIT Kerberos 5, Heimdal
279 Kerberos 5 and CyberSafe Kerberos 5).  These mechanisms make use of the kerberos infrastructure
280 and thus have no password database.
281
282 <p>Applications that wish to use a kerberos mechanism will need access
283 to a service key, stored either in a "srvtab" file (Kerberos 4) or a
284 "keytab" file (Kerberos 5).  Currently, the keytab file location is
285 not configurable and defaults to the system default (probably
286 <tt>/etc/krb5.keytab</tt>).
287
288 <p>The Kerberos 4 srvtab file location is configurable; by default it is
289 <tt>/etc/srvtab</tt>, but this is modifiable by the "srvtab" option.
290 Different SASL applications can use different srvtab files.
291
292 <p>A SASL application must be able to read its srvtab or keytab file.
293
294 <p>You may want to consult the <a href="gssapi.html">GSSAPI Tutorial</a>.</p>
295
296 <h3>The OTP mechanism</h3>
297
298 The Cyrus SASL library also supports the One-Time-Password (OTP)
299 mechanism.  This mechanism is similar to CRAM-MD5 and DIGEST-MD5 in
300 that is uses a shared secret and a challenge/response exchange.
301 However, OTP is more secure than the other shared secret mechanisms in
302 that the secret is used to generate a sequence of one-time (single
303 use) passwords which prevents reply attacks, and that secret need
304 not be stored on the system.  These one-time passwords are stored in the
305 <tt>/etc/sasldb2</tt> database.  See the <i>Shared secrets
306 mechanisms</i> section for a discussion of the <tt>/etc/sasldb2</tt>
307 database.
308
309 <h4>OTP via OPIE</h4>
310 For sites with an existing OTP infrastructure using OPIE, Cyrus SASL
311 can be configured to use OPIE v2.4 instead of using its own database
312 and server-side routines.
313 OPIE should be configured with the <tt>--disable-user-locking</tt> 
314 option if the SASL server application will not be running as "root". 
315
316 <p>OPIE uses its own "opiekeys" database for storing the data necessary
317 for generating the server challenges.  The location of the opiekeys
318 file is configurable in SASL; by default it is <tt>/etc/opiekeys</tt>,
319 but this is modifiable by the "opiekeys" option.
320
321 <p>A SASL server application must be able to read and write the
322 opiekeys file.
323
324 <h2>Auxiliary Properties</h2>
325
326 SASLv2 introduces the concept of Auxilliary Properties.  That is, the ability
327 for information related to authentication and authorization to all be looked
328 up at once from a directory during the authentication process.  SASL Plugins
329 internally take advantage of this to do password lookups in directories
330 such as the SASLdb, LDAP or a SQL database.  Applications can look up arbitrary properties through them.<p>
331
332 Note that this means that if your password database is in a SASLdb, and
333 you wish to use it for plaintext password lookups through the sasldb, you
334 will need to set the sasl <a href=options.html>option</a>
335 <tt>pwcheck_method</tt> to be <tt>auxprop</tt>. 
336
337 <h2>How to set configuration options</h2>
338
339 The Cyrus SASL library comes with a built-in configuration file
340 reader.  However, it is also possible for applications to redefine
341 where the library gets it's configuration options from.
342
343 <h3><a name="saslconf">The default configuration file</a></h3>
344
345 <p>By default, the Cyrus SASL library reads it's options from
346 <tt>/usr/lib/sasl2/App.conf</tt> (where "App" is the application
347 defined name of the application).  For instance, Sendmail reads it's
348 configuration from "<tt>/usr/lib/sasl2/Sendmail.conf</tt>" and the
349 sample server application included with the library looks in
350 "<tt>/usr/lib/sasl2/sample.conf</tt>".
351
352 <p>A standard Cyrus SASL configuration file looks like: 
353 <pre>
354 srvtab: /var/app/srvtab
355 pwcheck_method: saslauthd
356 </pre>
357
358 <h3>Application configuration</h3>
359
360 Applications can redefine how the SASL library looks for configuration
361 information.  Check your application's documentation for specifics.
362
363 <p>For instance, Cyrus imapd reads its sasl options from it's own
364 configuration file, <tt>/etc/imapd.conf</tt>, by prepending all SASL
365 options with "<tt>sasl_</tt>": the SASL option "pwcheck_method" is set
366 by changing "sasl_pwcheck_method" in <tt>/etc/imapd.conf</tt>.
367
368 <h2>Troubleshooting</h2>
369
370 <dl compact>
371 <dt><b>Q:</b> Why doesn't KERBEROS_V4 doesn't appear as an
372 available mechanism?
373 <dd>
374 <p><b>A:</b> Check that the <tt>srvtab</tt> file is readable by the
375 user running as the daemon.  For Cyrus imapd, it must be readable by
376 the Cyrus user.  By default, the library looks for the srvtab in
377 <tt>/etc/srvtab</tt>, but it's configurable using the <tt>srvtab</tt>
378 option.
379
380 <p>
381 <dt><b>Q:</b> Why doesn't OTP doesn't appear as an available
382 mechanism?
383 <dd>
384 <p><b>A:</b> If using OPIE, check that the <tt>opiekeys</tt> file is
385 readable by the user running the daemon.  For Cyrus imapd, it must
386 be readable by the Cyrus user.  By default, the library looks for the
387 opiekeys in <tt>/etc/opiekeys</tt>, but it's configurable using the
388 <tt>opiekeys</tt> option.
389
390 <p>
391 <dt><b>Q:</b> Why don't CRAM-MD5 and DIGEST-MD5 work with my old sasldb?
392 <dd>
393 <p><b>A:</b> Because sasldb now stores plaintext passwords only, the old
394 sasldb is completely incompatible.
395
396 <p>
397 <dt><b>Q:</b> I'm having performance problems on each authentication, there is
398 a noticeable slowdown when sasl initializes, what can I do?
399 <dd>
400 <p><b>A:</b>libsasl reads from <tt>/dev/random</tt> as part of its
401 initialization. <tt>/dev/random</tt> is a "secure" source of entropy,
402 and will block your application until a sufficient amount of
403 randomness has been collected to meet libsasl's needs.</p>
404
405 <p>To improve performance, you can change DEV_RANDOM in
406 <tt>config.h</tt> to be <tt>/dev/urandom</tt> and recompile
407 libsasl. <tt>/dev/urandom</tt> offers less secure random numbers but
408 should return immediately. The included mechanisms, besides OTP and
409 SRP, use random numbers only to generate nonces, so using
410 <tt>/dev/urandom</tt> is safe if you aren't using OTP or SRP.
411
412 <p>
413 <dt><b>Q:</b> I've converted the sasldb database to the new format. 
414 Why can't anybody authenticate?
415 <dd>
416 <p><b>A:</b> sasldb is now a plugin module for the auxprop method.
417 Make sure you changed the /usr/lib/sasl2/*.conf files to reflect<br>
418 <tt>pwcheck_method: auxprop</tt><br>
419 <br>
420 ...and if you're using cyrus-imapd, /etc/imapd.conf must reflect:
421 <tt>sasl_pwcheck_method: auxprop</tt>
422
423 <p>
424 <dt><b>Q:</b> Is LOGIN supported?
425 <dd>
426 <p><b>A:</b> The LOGIN mechanism is a non-standard, undocumented
427 plaintext mechanism.  It's included in the SASL distribution purely
428 for sites that need it to interoperate with old clients; we don't
429 support it.  Don't enable it unless you know you need it.
430
431 <p>
432 <dt><b>Q:</b> Is NTLM supported?
433 <dd>
434 <p><b>A:</b> The NTLM mechanism is a non-standard, undocumented
435 mechanism developed by Microsoft.  It's included in the SASL
436 distribution purely for sites that need it to interoperate with
437 Microsoft clients (ie, Outlook) and/or servers (ie, Exchange); we
438 don't support it.  Don't enable it unless you know you need it.
439
440 <p>
441 <dt><b>Q:</b> How can I get a non-root application to check plaintext
442 passwords?
443 <dd>
444 <p><b>A:</b> Use the "saslauthd" daemon and setting "pwcheck_method"
445 to "saslauthd".
446
447 <p>
448 <dt><b>Q:</b> I want to use Berkeley DB, but it's installed in
449 <tt>/usr/local/BerkeleyDB.3.1</tt> and <tt>configure</tt> can't find
450 it.
451 <dd>
452 <p><b>A:</b> Try setting "CPPFLAGS" and "LDFLAGS" environment
453 variables before running <tt>configure</tt>, like so:
454 <pre>
455 env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" \
456   LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib -R/usr/local/BerkeleyDB.3.1/lib" \
457   ./configure --with-dblib=berkeley 
458 </pre>
459
460 <p>
461 <dt><b>Q:</b> It's not working and won't tell me why! Help!
462 <dd>
463 <p><b>A:</b> Check syslog output (usually stored in
464 <tt>/var/log</tt>) for more information. You might want to change your
465 syslog configuration (usually <tt>/etc/syslogd.conf</tt>) to log
466 "debug.*" to a file while debugging a problem.</p>
467
468 <p>The developers make heavy use of <tt>strace</tt> or <tt>truss</tt>
469 when debugging a problem that isn't outputting any useful
470 information.</p>
471
472 <p>
473 <dt><b>Q:</b> Is there a mailing list to discuss the Cyrus SASL
474 library?
475 <dd>
476 <p><b>A:</b> <tt>cyrus-sasl@lists.andrew.cmu.edu</tt> is available for
477 discussion.  To subscribe, send a message to
478 <a href=
479 "mailto:majordomo@lists.andrew.cmu.edu?subject=subscribe cyrus-sasl">
480 <tt>majordomo@lists.andrew.cmu.edu</tt></a>
481 with the body of 'subscribe cyrus-sasl'.
482
483 <p> An archive is available via
484 <ul>
485  <li> anonymous IMAP at <a
486 href="imap://cyrus.andrew.cmu.edu/archive.cyrus-sasl">imap://cyrus.andrew.cmu.edu/archive.cyrus-sasl</a>.
487   <li> HTTP at <a
488 href="http://asg.web.cmu.edu/archive/mailbox.php3?mailbox=archive.cyrus-sasl">
489 http://asg.web.cmu.edu/archive/mailbox.php3?mailbox=archive.cyrus-sasl</a>
490 </ul>
491
492 <p>Note: If you are not subscribed, your posts go through human
493 approval before they go out to the list and so posting may be
494 (greatly) delayed.
495 </dl>
496
497 <hr>
498 Back to the <A href=index.html>index</a>
499
500 </body>
501 </html>
502