Software: Apache/2.2.3 (CentOS). PHP/5.1.6 

uname -a: Linux mx-ll-110-164-51-230.static.3bb.co.th 2.6.18-194.el5PAE #1 SMP Fri Apr 2 15:37:44
EDT 2010 i686 

uid=48(apache) gid=48(apache) groups=48(apache) 

Safe-mode: OFF (not secure)

/usr/share/doc/cyrus-sasl-lib-2.1.22/   drwxr-xr-x
Free 50.94 GB of 127.8 GB (39.86%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     sysadmin.html (21.85 KB)      -rw-r--r--

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 its 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). See your application's documentation for details about changing the default proxy/authorization policies.

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 your databases.

To add users of different realms to sasldb, you can use the -u option to saslpasswd2. The SQL plugin has a way of integrating the realm name into the query string with the '%r' macro.

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.

Realms will be passed to saslauthd as part of the saslauthd protocol, however the way each saslauthd module deals with the situation is different (for example, the LDAP plugin allows you to use the realm to query the server, while the rimap and PAM plugins ignore it entirely).

Realms are represented in a username string by any text followinhg the '@' sign. So, usernames like rjs3@ANDREW.CMU.EDU, is user 'rjs3' in the realm 'ANDREW.CMU.EDU'. If no realm is provided, the server's FQDN is assumed (likewise when specifying a realm for saslpasswd2).

How SASL works

The PLAIN mechanism, sasl_checkpass(), and plaintext passwords

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

auxprop

checks passwords agains the userPassword attribute supplied by an auxiliary property plugin. For example, SASL ships with a sasldb auxiliary property plugin, that can be used to authenticate against the passwords stored in /etc/sasldb2. Since other mechanisms also use this database for passwords, using this method will allow SASL to provide a uniform password database to a large number of mechanisms.

saslauthd

contacts the saslauthd daemon to to check passwords using a variety of mechanisms. More information about the various invocations of saslauthd can be can be found in saslauthd(8). Generally you want something like saslauthd -a pam. If plaintext authentications seem to be taking some time under load, increasing the value of the -n parameter can help.

Saslauthd keeps its named socket in "/var/state/saslauthd" by default. This can be overridden by specifying an alternate value to --with-saslauthd=/foo/bar at compile time, or by passing the -m parameter to saslauthd (along with setting the saslauthd_path SASL option). Whatever directory this is, it must exist in order for saslauthd to function.

Once you configure (and start) saslauthd, there is a testsaslauthd program that can be built with make testsaslauthd in the saslauthd subdirectory of the source. This can be used to check that that the saslauthd daemon is installed and running properly. An invocation like testsaslauthd -u rjs3 -p 1234 with appropriate values for the username and password should do the trick.

If you are using the PAM method to verify passwords with saslauthd, keep in mind that your PAM configuration will need to be configured for each service name that is using saslauthd for authentication. Common service names are "imap", "sieve", and "smtp".

Courier-IMAP authdaemond

contacts Courier-IMAP's authdaemond daemon to check passwords. This daemon is simliar in functionality to saslauthd, and is shipped separately with the Courier mail server.

Note: this feature is not compiled in the library by default, and its provided for sites with custom/special requirements only (because the internal authentication protocol its not documented anywhere so it could change at any time). We have tested against the authdaemond included with Courier-IMAP 2.2.1.

To enable authdaemond support, pass --with-authdaemon to the configuration script, set pwcheck_method to ``authdaemond'' and point authdaemon_path to authdaemond's unix socket. Optionally, you can specify --with-authdaemond=PATH to the configure script so that authdaemond_path points to a default, static, location.

pwcheck

checks passwords with the use of a separate, helper daemon. This feature is for backwards-compatibility only. New installations should use saslauthd.

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!

However, the more flexible and preferred method of adding a routine is to create a new saslauthd mechanism.

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 passwords or password equivalents in a database; if this database is compromised, it is the same as if all the passwords for the realm are compromised.

Put another way, you cannot use saslauthd with these methods. If you do not wish to advertise these methods for that reason (i.e. you are only using saslauthd for password verification), then either remove the non-plaintext plugins (those other than login and plain) from the plugin directory, or use the mech_list option to disable them.

For simplicity sake, the Cyrus SASL library stores plaintext passwords only in the /etc/sasldb2 database. These passwords are then shared among all mechanisms which choose to use it. 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.

This point is important, so we will repeat it: sasldb stores the plaintext versions of all of its passwords. If it is compromised so are all of the passwords that it stores.

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 "saslpasswd2" 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 "auxprop", and the sasldb plugin is installed, since you'll be transitioning from a plaintext store to a plaintext store)

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.

The OTP mechanism

OTP via OPIE

OPIE uses its own "opiekeys" database for storing the data necessary for generating the server challenges. The location of the opiekeys file is configurable in SASL; by default it is /etc/opiekeys, but this is modifiable by the "opiekeys" option.

A SASL server application must be able to read and write the opiekeys file.

Auxiliary Properties

Note that this means that if your password database is in a SASLdb, and you wish to use it for plaintext password lookups through the sasldb, you will need to set the sasl option pwcheck_method to be auxprop.

How to set configuration options

The default configuration file

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

A standard Cyrus SASL configuration file looks like:

srvtab: /var/app/srvtab
pwcheck_method: saslauthd

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.

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 doesn't OTP doesn't appear as an available mechanism?

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

Q: Why don't CRAM-MD5 and DIGEST-MD5 work with my old sasldb?

A: Because sasldb now stores plaintext passwords only, the old sasldb is completely incompatible.

Q: I'm having performance problems on each authentication, there is a noticeable slowdown when sasl initializes, what can I do?

A:libsasl reads from /dev/random as part of its initialization. /dev/random is a "secure" source of entropy, and will block your application until a sufficient amount of randomness has been collected to meet libsasl's needs.

To improve performance, you can change DEV_RANDOM in config.h to be /dev/urandom and recompile libsasl. /dev/urandom offers less secure random numbers but should return immediately. The included mechanisms, besides OTP and SRP, use random numbers only to generate nonces, so using /dev/urandom is safe if you aren't using OTP or SRP.

Q: I've converted the sasldb database to the new format. Why can't anybody authenticate?

A: sasldb is now a plugin module for the auxprop method. Make sure you changed the /usr/lib/sasl2/*.conf files to reflect
pwcheck_method: auxprop

...and if you're using cyrus-imapd, /etc/imapd.conf must reflect: sasl_pwcheck_method: auxprop

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: Is NTLM supported?

A: The NTLM mechanism is a non-standard, undocumented mechanism developed by Microsoft. It's included in the SASL distribution purely for sites that need it to interoperate with Microsoft clients (ie, Outlook) and/or servers (ie, Exchange); we don't support it. Don't enable it unless you know you need it.

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

A: Use the "saslauthd" daemon and setting "pwcheck_method" to "saslauthd".

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: It's not working and won't tell me why! Help!

A: Check syslog output (usually stored in /var/log) for more information. You might want to change your syslog configuration (usually /etc/syslogd.conf) to log "debug.*" to a file while debugging a problem.

The developers make heavy use of strace or truss when debugging a problem that isn't outputting any useful information.

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.