$Id: README,v 1.25.4.2 2001/06/27 20:13:29 rjs3 Exp $

This is the Cyrus SASL API implentation. It can be used on the client
or server side to provide authentication. 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.

ALPHA WARNING
-------------
THIS CODE IS ALPHA-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.

In order to get RC4 encryption under DIGEST-MD5, you'll need an
implementation of RC4.  This might be export controlled (which is why
it's a seperate package); if you think you have an export license,
know that don't need one, or aren't planning to export it, it's
available under <http://andrew2.andrew.cmu.edu/dist/>.  SASL can also
use the OpenSSL version of RC4, available from <http://www.openssl.org/>.

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.

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: [sasldb] one of {PAM, kerberos_v4, passwd, shadow, sasldb}
	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.

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.

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", draft-leach-digest-sasl-03.txt, work in progress.

[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",
draft-newman-tls-imappop-xx.txt, work in progress.

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