Cyrus SASLv2 README

# Read Me First

This document offers a general overview of the SASL library.

## FEATURES

The following mechanisms are included in this distribution:

- ANONYMOUS
- CRAM-MD5
- DIGEST-MD5
- GSSAPI (MIT Kerberos 5 or Heimdal Kerberos 5)
- KERBEROS_V4
- PLAIN
- OTP (requires OpenSSL libcrypto)
- SRP (work in progress; requires OpenSSL libcrypto)

The library uses a Berkeley DB, gdbm or ndbm file on the server side to store per-user authentication secrets. The utility `saslpasswd` has been included for adding authentication secrets to the file.

PLAIN uses sasldb, the pwcheck daemon, or the saslauthd daemon.

The sample directory contains two programs which provide a reference for using the library, as well as making it easy to test a mechanism on the command line. See programming.html for more information.

This library is believed to be thread safe IF:

- you supply mutex functions (see sasl_set_mutex())
- you make no libsasl calls until sasl_client/server_init() completes
- no libsasl calls are made after sasl_done() is begun
- the GSSAPI plugin requires a thread-safe GSS Kerberos 5 library.

## INSTALLATION

If you are upgrading from libsasl v1, please see upgrading.html.

Please see the file install.html to install this package. We hope it to be relatively straightforward; if you try it on systems that we haven't, please contact us with your experiences.

The library uses the environment variable SASL_PATH to locate the directory where the mechanisms are; this should be a colon-separated list of directories containing plugins.

## INSTALLATION ON MAC OS X

Please read macosx.html

## CONFIGURATION

By default, libsasl looks for configuration files in /usr/lib/sasl/Appname.conf where Appname is settable by the application (for example, Sendmail 8.10 and later set this to "Sendmail"). Applications can also override this default configuration mechanism.

For a detailed guide on configuring libsasl, please look at sysadmin.html and options.html

## KNOWN BUGS

- There are some interoperability problems with the DIGEST-MD5 plugin.
- There is an API issue with the username canonicalization functions which will be fixed by the next release.
- libtool doesn't always link libraries together. In our environment, we only have static Krb5 libraries; the GSSAPI plugin should link these libraries in on platforms that support it (Solaris and Linux among them) but it does not. It also doesn't always get the runpath of libraries correct.
- Also see the "TODO" file and our bugzilla.

## UPGRADING from Cyrus SASL v1

See upgrading.html.

## AUTHORS

For any comments/suggestions/bug reports, please contact cyrus-bugs@andrew.cmu.edu. Be sure to include the version of libsasl and your operating system; messages without this information will not be answered.

Major contributors to the libsasl code can be found in the top-level file AUTHORS.

Back to the index