	      Programming with SASL (a work in progress)
			 by Larry Greenfield

Eventually, I hope to expand this into workable documentation for
using the SASL library with various programs.  For now, all I have is
what isn't implemented.  For guidance in using the library, take a
look at the sample/ directory.  For a "real world" example of
applications that use SASL, please see the Cyrus IMAP server, version
1.6.0 or later.

I. Example applications

A. sample-client, sample-server

The sample client and server included with this distribution were
really written to help debug mechanisms.  They base64 encode all the
data and print it out on standard output.

Make sure that you set the IP addresses on the command line (some
mechanisms depend on this).

Also, sometimes you'll get "realm: Information not available" sort of
messages; this is due to the fact that some mechanisms don't have a
concept of "realm", and therefore never set them.

B. cyrus imapd v1.6.0 or later

The Cyrus imap server now incorporates SASL for all it's
authentication needs.  It is a good example of a fairly large server
application.  Also of interest is the prot layer, included in
libcyrus.  This is a stdio-like interface that automatically takes
care of layers using a simple "prot_setsasl()" call.

It also sets a SASL_CB_PROXY_POLICY callback, which should be of
interest to many applications.

C. imtest, from cyrus imapd 1.6.0 or later

imtest is an application included with Cyrus imapd.  It is a very
simple IMAP client, but should be of interest to people who are
writing applications.  It also uses the prot layer, but it is easy to
incorporate similiar support without using the prot layer.

II. Random Things

A. Empty exchanges

Some SASL mechanisms intentionally send no data; your application should
be prepared to either send or receive an empty exchange.  The SASL
profile for the protocol should define how to send an empty string;
make sure you send an empty string when requested to, and when you
receive an empty string make sure that the "inlength" is 0.

III. What's Not Implemented

Some parts of this API aren't implemented by this implementation.  In
brief:

A. Credentials

None of the modules support passing credentials.  In the future, we
hope to add credential passing to the modules that support it (most
likely the Kerberos modules).  Thus, an application that specifies
SASL_SEC_PASS_CREDENTIALS will not receive any mechanisms.  The
functions sasl_cred_install() and sasl_cred_uninstall() do nothing.

The credentials API is likely to change.

B. Secrets

sasl_client_auth() is unimplemented.  It is unclear what this is
intended for.  If we implement it, it will probably be for generating
secrets for fast reauthentication.

The "secret" parameter to sasl_client_start is unused.  It is likely
that this was intended for fast reauthentication.

C. Idle

While the implementation & plugins correctly implement the idle calls,
none of them currently do anything.

$Id: programming,v 1.2 1999/07/30 19:00:17 leg Exp $
