Whole document tree

Cyrus SASL for System Administrators

What SASL is

Applications use the SASL library to tell them how to accomplish the SASL protocol exchange, and what the results were.

SASL is only a framework: specific SASL mechanisms govern the exact protocol exchange. If there are n protocols and m different ways of authenticating, SASL attempts to make it so only n plus m different specifications need be written instead of n times m different specifications. With the Cyrus SASL library, the mechanisms need only be written once, and they'll work with all servers that use it.

Authentication and authorization identifiers

userid (user id, authorization id)

The userid is the identifier an application uses to check allowable options. On my Unix system, the user "bovik" (the account of Harry Q. Bovik) is allowed to write to "/home/bovik" and it's subdirectories but not to "/etc".

authid (authentication id)

The authentication identifier is the identifier that is being checked. "bovik"'s password might be "qqqq", and the system will authenticate anyone who knows "qqqq" as "bovik". However, it's possible to authenticate as one user but act as another user. For instance, Harry might be away on vacation and assign one of his graduate students, Jane, to read his mail. He might then allow Jane to act as him merely by supplying her password and her id as authentication but requesting authorization as "bovik". So Jane might log in with an authentication identifier of "jane" and an authorization id of "bovik" and her own (Jane's) password.

Applications can set their own proxy policies; by default, the SASL library will only allow the same user to act for another (that is, userid must equal authid).

Realms

In the simplest case, a single server on a single machine, the realm might be the fully-qualified domain name of the server. If the applications don't specify a realm to SASL, most mechanisms will default to this.

If a site wishes to share passwords between multiple machines, it might choose it's authentication realm as a domain name, such as "CMU.EDU". On the other hand, in order to prevent the entire site's security from being compromised when one machine is compromised, each server could have it's own realm. Certain mechanisms force the user (client side) to manually configure what realm they're in, making it harder for users to authenticate.

A single site might support multiple different realms. This can confuse applications that weren't written in anticipation of this; make sure your application can support it before adding users from different realms into sasldb with saslpasswd.

The Kerberos mechanisms treat the SASL realm as the Kerberos realm. Thus, the realm for Kerberos mechanisms defaults to the default Kerberos realm on the server. They may support cross-realm authentication; check your application on how it deals with this.

How SASL works

The PLAIN mechanism, sasl_checkpass(), and plaintext passwords

The principal concern for system administrators is how the authentication and password are verified. The Cyrus SASL library is flexible in this regard:

passwd

/etc/passwd, via the call getpwnam(), is supported innately in the library. Simply set the configuration option "pwcheck_method" to "passwd".

shadow

/etc/shadow is somewhat trickier. If the servers that use SASL run as root (such as Sendmail) there's no problem: just set the "pwcheck_method" option to "shadow". However, many daemons do not run as root for additional security, such as Cyrus imapd. In order for these servers to check passwords, they either need a helper program that runs as root, or need special privileges to read /etc/shadow. The easiest way is to give the server the rights to read /etc/shadow by, for instance, adding the cyrus user to the "shadow" group and then setting "pwcheck_method" to "shadow".

Another possible approach to check shadow passwords is the pwcheck daemon.

sia

Security Integration Architecture is the secure method of authenticating users on Digital Unix. It should be used especially if C2 level security is enabled. This type must be explicitly enabled at compile time.

kerberos_v4

Kerberos v4, if found by the configuration script at compile time, can be enabled for plaintext password checking by setting "pwcheck_method" to "kerberos_v4". This is different from the KERBEROS_V4 mechanism discussed below---this configuration option merely specifies how to check plaintext passwords on the server.

pam

PAM, the pluggable authentication module, is the default way of authenticating users on Solaris and Linux. It can be configured to check passwords in many different ways: through Radius, through NIS, through LDAP, or even using the traditional /etc/passwd file. If you wish to use PAM for authentication and the Cyrus SASL library found the PAM library when it was configured at compilation time, set "pwcheck_method" to "PAM". It uses PAM with the service name (for example, Sendmail uses "smtp" and Cyrus imapd uses "imap").

The PAM authentication for SASL only affects the plaintext authentication it does. It has no effect on the other mechanisms, so it is incorrect to try to use PAM to enforce additional restrictions beyond correct password on an application that uses SASL for authentication.

sasldb

This stores passwords in the SASL secrets database, the same database that stores the secrets for shared secret methods. Its principal advantages are that passwords used by the shared secrets mechanisms will be in sync with the plaintext password mechanisms and that this is the only plaintext authentication method that supports multiple realms on a single server. However, system built-in routines will not use sasldb.

(sasldb is the default method.)

pwcheck

checks passwords with the use of a seperate, helper daemon. needs to be documented.

write your own

Last, but not least, the most flexible method of authentication for PLAIN is to write your own. If you do so, any application that calls the "sasl_checkpass()" routine or uses PLAIN will invoke your code. The easiest place to modify the plaintext authentication routines is to modify the routine "_sasl_checkpass()" in the file lib/server.c to support a new method, and to add that method to lib/checkpw.c. Be sure to add a prototype in lib/saslint.h! (tell people to use pwcheck?)

The LOGIN mechanism (not to be confused with IMAP4's LOGIN command) is an undocumented, unsupported mechanism. It's included in the Cyrus SASL distribution for the sake of SMTP servers that might want to interoperate with old clients. Do not enable this mechanism unless you know you're going to need it. When enabled, it verifies passwords the same way the PLAIN mechanism does.

Shared secrets mechanisms

There's a downside: in order to verify such responses, the server must keep password equivalents in a database; if this database is compromised, it is the same as if all the passwords for the realm are compromised.

The Cyrus SASL library stores these secrets in the /etc/sasldb database. Depending on the exact database method used (gdbm, ndbm, or db) the file may have different suffixes or may even have two different files ("sasldb.dir" and "sasldb.pag"). It is also possible for a server to define it's own way of storing authentication secrets. Currently, no application is known to do this.

The principle problem for a system administrator is to make sure that sasldb is properly protected; only the servers that need to read it to verify passwords should be able to. If there are any normal shell users on the system, they must not be able to read it.

Managing password changes is outside the scope of the library. However, system administrators should probably make a way of letting user's change their passwords available to users. The "saslpasswd" utility is provided to change the secrets in sasldb. It does not affect PAM, /etc/passwd, or any other standard system library; it only affects secrets stored in sasldb.

Finally, system administrators should think if they want to enable "auto_transition". If set, the library will automatically create secrets in sasldb when a user uses PLAIN to successfully authenticate. However, this means that the individual servers, such as imapd, need read/write access to sasldb, not just read access. By default, "auto_transition" is set to false; set it to true to enable. (There's no point in enabling this option if "pwcheck_method" is "sasldb".)

Kerberos mechanisms

Applications that wish to use a kerberos mechanism will need access to a service key, stored either in a "srvtab" file (Kerberos 4) or a "keytab" file (Kerberos 5). Currently, the keytab file location is not configurable and defaults to the system default (probably /etc/krb5.keytab).

The Kerberos 4 srvtab file location is configurable; by default it is /etc/srvtab, but this is modifiable by the "srvtab" option. Different SASL applications can use different srvtab files.

A SASL application must be able to read its srvtab or keytab file.

You may want to consult the GSSAPI Tutorial.

How to set configuration options

The default configuration file

By default, the Cyrus SASL library reads it's options from /usr/lib/sasl/App.conf (where "App" is the application defined name of the application). For instance, Sendmail reads it's configuration from "/usr/lib/sasl/Sendmail.conf" and the sample server application included with the library looks in "/usr/lib/sasl/sample.conf".

A standard Cyrus SASL configuration file looks like:

srvtab: /var/app/srvtab
pwcheck_method: kerberos_v4

Application configuration

For instance, Cyrus imapd reads its sasl options from it's own configuration file, /etc/imapd.conf, by prepending all SASL options with "sasl_": the SASL option "pwcheck_method" is set by changing "sasl_pwcheck_method" in /etc/imapd.conf. Check your application's documentation for more information.

Compiling and installing the library

what configure options to use?

don't install a mechanism you aren't going to use.

use --disable-krb4 and --disable-gssapi if you aren't a kerberos site.

use --disable-cram and --disable-digest if you can't use shared secret mechanisms.

need pwcheck? use --enable-pwcheck

other stuff

what can go wrong with shared libraries?

make sure to make the /usr/lib/sasl symbolic link.

Unfortunately, since SASL is very flexible (allowing administrators to upgrade and install new authentication plugins without recompiling any applications) its flexibility can also make it a chore to compile.

I'll have some sage advice here when I find some.

Troubleshooting

Q: Why doesn't KERBEROS_V4 doesn't appear as an available mechanism?

A: Check that the srvtab file is readable by the user running as the daemon. For Cyrus imapd, it must be readable by the Cyrus user. By default, the library looks for the srvtab in /etc/srvtab, but it's configurable using the srvtab option.

Q: Why don't CRAM-MD5 and DIGEST-MD5 appear as an available mechanisms?

A: The mechanisms won't appear until after some users have been created. Use saslpasswd to create a user.

Q: CRAM-MD5 and DIGEST-MD5 used to appear, but since I've upgraded they don't anymore!

A: As of Cyrus SASL 1.5.13, we've added a versioning feature into the database. If you're upgrading from before 1.5.13, you'll have to use saslpasswd to set a password.

If you're upgrading from 1.5.13 or later, check the syslog messages; if it indicates an incompatible version number, there's probably a conversion tool you'll have to run.

Q: Is LOGIN supported?

A: The LOGIN mechanism is a non-standard, undocumented plaintext mechanism. It's included in the SASL distribution purely for sites that need it to interoperate with old clients; we don't support it. Don't enable it unless you know you need it.

Q: How come PAM doesn't work as an plaintext verifier?

A: Check your PAM configuration. On Solaris, it's generally found in /etc/pam.conf. On Linux, it's usually in the directory /etc/pam.d. You'll have to configure PAM for the service you're providing: "smtp" for Sendmail, or "imap" and "pop" for Cyrus.

Q: How can I get a non-root application to check plaintext passwords?

A: Try using the "pwcheck" daemon and setting "pwcheck_method" to "pwcheck". You'll have to run configure with the --with-pwcheck option.

Q: I want to use Berkeley DB, but it's installed in /usr/local/BerkeleyDB.3.1 and configure can't find it.

A: Try setting "CPPFLAGS" and "LDFLAGS" environment variables before running configure, like so:

env CPPFLAGS="-I/usr/local/BerkeleyDB.3.1/include" \
  LDFLAGS="-L/usr/local/BerkeleyDB.3.1/lib -R/usr/local/BerkeleyDB.3.1/lib" \
  ./configure --with-dblib=berkeley 

Q: Is there a mailing list to discuss the Cyrus SASL library?

A: cyrus-sasl@lists.andrew.cmu.edu is available for discussion. To subscribe, send a message to majordomo@lists.andrew.cmu.edu with the body of 'subscribe cyrus-sasl'.

An archive is available via

• anonymous IMAP at imap://cyrus.andrew.cmu.edu/archive.cyrus-sasl.
• HTTP at http://asg.web.cmu.edu/archive/mailbox.php3?mailbox=archive.cyrus-sasl

Note: If you are not subscribed, your posts go through human approval before they go out to the list and so posting may be (greatly) delayed.