$Id: README,v 1.25.4.6 2001/08/24 23:24:27 rbraun Exp $

This is the Cyrus SASL API implentation. It can be used on the client
or server side to provide authentication and authorization services.
See RFC 2222 for more information.

The latest version is available at:
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail

There's a mailing list for Cyrus SASL.  Subscribe by sending a message
to majordomo@lists.andrew.cmu.edu with the body "subscribe
cyrus-sasl". The mailing list is available via anonymous IMAP at
imap://cyrus.andrew.cmu.edu/archive.cyrus-sasl or via the web at
http://asg.web.cmu.edu/archive/mailbox.php3?mailbox=archive.cyrus-sasl.

BETA WARNING
-------------
THIS CODE IS BETA-QUALITY AND IS INTENDED FOR DEVELOPERS ONLY.
IT IS NOT BACKWARDS COMPATIBLE WITH SASLv1.

Bugs can be searched/reported at: http://bugzilla.andrew.cmu.edu

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

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 "docs/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 SASL calls until sasl_client/server_init() completes
-no SASL calls are made after sasl_done() is begun

INSTALLATION
------------
Please see the file "INSTALL" 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-seperated
list of directories containing plugins.

INSTALLATION ON MAC OS X
------------------------
Please read the file doc/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.

Currently configurable parameters:
- srvtab (for KERBEROS_V4): [/etc/srvtab] path
	where to find the srvtab

- pwcheck_method: [auxprop] one of {auxprop, pwcheck, saslauthd}
	how to check plaintext passwords.

- auto_transition: [false]
	if true, automatically add secrets to the secret database when
	PLAIN or check_password is used, so in the future the user can
	use the more secure mechanisms.

*** For a more detailed guide on configuring SASL, please look at
doc/sysadmin.html and doc/options.html.

KNOWN BUGS
----------
* 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.

UPGRADING
---------
SASLv2 is completely incompatible with SASLv1.  That means applications are
unable to link both versions of the library, and applications built to
use one version cannot use the other (atleast not without serious pain
and suffering on the part of the developer).

Likewise, "sasldb" is incompatible between SASLv1 and SASLv2. As of this time
there is no migration utility because the passwords in the SASLv1 database
are all encrypted, so there is no easy way to extract them.  (Note that
as sasldb support has been extracted from the main library into an auxprop
plugin, thew default pwcheck_method is now "auxprop", which does auxprop
lookups in search of the userPassword property)

Note that all passwords in the SASLv2 version of sasldb are stored in plain
text format.  That means that a comprimized sasldb comprimizes all services
that rely upon it.  Note also that this situation is not significantly worse,
cryptographicly speaking, than the old method, and allows the database
to be easy to transition to another format, should the need arise.  Mechanisms
wishing a more secure password database backend should implement their own.

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.

Authors can be found in the file AUTHORS.

REFERENCES
----------
[ANONYMOUS] Newman, C., "Anonymous SASL Mechanism", RFC 2245, November
1997.

[CRAM-MD5] Klensin, Catoe, Krumviede, "IMAP/POP AUTHorize Extension
for Simple Challenge/Response", RFC 2195, September 1997.

[DIGEST-MD5] Leach, Newman, "Using Digest Authentication as a SASL
Mechanism", RFC 2831, May 2000

[KEYED-MD5] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, February 1997. 

[PLAIN] Newman, C., "Using TLS with IMAP4, POP3 and ACAP",
RFC 2595, June 1999

[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
