$Id: README,v 1.14 1999/08/21 03:05:14 leg 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".

UPGRADING FROM PREVIOUS VERSIONS
--------------------------------

Upgrading from versions 1.5.4 or earlier:
  The secrets database has changed formats in 1.5.5.

  Edit util/dbconverter.c to select whether you use gdbm or ndbm, and
  compile util/dbconverter.c:
  % gcc dbconverter.c -lsasl -o dbconverter

  You have a one-time opportunity to insert PLAIN secrets in the sasl
  database.  If you wish to enable checking plaintext passwords via
  the sasl secrets database, set "pwcheck_method" to "sasldb":
  % cat /usr/lib/sasl/saslpasswd.conf
  pwcheck_method: sasldb
  %

  Run dbconverter as a user with sufficient permissions to write to
  /etc/sasldb as follows:
  
  % dbconverter /etc/saslbackup platypus.cc.cmu.edu

  Replace "platypus.cc.cmu.edu" with your realm (usually just your
  hostname).

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 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 can either check /etc/passwd, Kerberos V4, use PAM, or the sasl
secrets database.  By default PAM is used if PAM is found, then
Kerberos, finally /etc/passwd (non-shadow).  This is tweakable in
the configuration file.  Please see "docs/sysadmin.html".

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.

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/>.  However, since
this release doesn't support encryption under DIGEST-MD5 (see below),
it doesn't matter anyway.

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, the Cyrus IMAP server sets this to "Cyrus").
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: [PAM] 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
----------
* SCRAM-MD5 is no longer being maintained, and probably needs some
work in order to be usable.

* DIGEST-MD5 has authentication implemented, but encryption and
integrity protection are disabled.  It is the view of the authors that
the current DIGEST-MD5 spec is ambiguous in regards to encryption.
The encryption implemented in the code generates RC4 in depth and thus
should not be used.

* The RC4 library is not always correctly found and dynamically
loaded.  This isn't regarded as a huge problem, since we aren't
supporting encryption in DIGEST-MD5 at this time.

* libtool doesn't always link libraries together.  In our environment,
we only have static Kerb5 libraries; the GSSAPI plugin should link
these libraries in on platforms that support it (Solaris and Linux
among them) but it does not.

* Also see the "TODO" file.

AUTHORS
-------
For any comments/suggestions/bug reports, please contact
cyrus-bugs@andrew.cmu.edu.

If you feel a great need to send mail to a person, contact Larry
Greenfield at leg+sasl@andrew.cmu.edu.

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.

[SCRAM-MD5] Newman, C., "Salted Challenge Response Authentication
Mechanism", draft-newman-auth-scram-xx.txt, Work in progress.
