SASL is Cyrus's Simple Authentication and Security Layer. And like every other Cyrus project I've seen, its a big mystery.
See SASL for information on what its (supposed) to do. See here for notes on its use.
libsasl has an unfortunate bug in that it is non re-entrant. This has the unfortunate effect of casuing segfaults in applications using libsasl.
I've seen this occur mainly when using libnss-ldap and libpam-ldap coupled with cyrus imapd. The big problem here is that both libldap2 and cyrus imapd's auth module are linked against libsasl - this can cause a chain of events which leads to a double free, which causes the application to die with SIGSEGV (SIG11, segmentation fault)
Solution: recompile libldap2 without cyrus sasl support.
The thing about SASL is that it sounds like a really really good idea. The bad thing about SASL is that it's a PITA. My biggest beef with SASL is that by default it doesn't do anything sane (like use PAM or /etc/passwd), it tries to use /etc/sasldb (or /etc/sasldb2 depending on the version of sasl). Of course when you first start looking at SASL you won't have anything in this file, so you won't be able to authenticate. Sigh.
You'll need to make sure you have SASL modules installed, if you don't, SASL will just fail. Sigh. Under debian you'll need libsasl2-modules at least, perhaps also libsasl2-gssapi-mit, libsasl2-krb4-mit, libsasl2-modules-gssapi-heimdal, and/or libsasl2-modules-kerberos-heimdal, but probably not.
now you should be able to authenticate using SASL. SASL will of course try and use the most secure authentication mechanism it can. This probably means that behind the scenes it will go off and do challenge response, and other magic. Good luck :)
in your slapd.conf, preferably before any other access directive. For more information about ldap access directives see LDAPNotes.
SASL stores passwords in /etc/sasldb and/or /etc/sasldb2 by default. Why it doesn't it do it somewhere in /var like it should is anyone's guess. However this means that /etc will have to be writable. Passwords are stored in these files in plain text, so make sure your permissions on them are correct. You can disable this by providing the -n parameter to saslpasswd2. You have been warned.
SASL has the concepts of realms. A "realm" is authentication mechanism dependant, but the general idea is that it works like a kerberos realm. By default you'll be using the realm which is the same as your hostname. If you're authenticating against a different host, make sure your realm is right or it isn't going to work. If you're using saslauthd with something like Cyrus doing virtual hosting you'll almost certainly need to start saslauthd with the -r argument to tell it to pass the full username (including the realm) through to the backend (eg. PAM)
SASL allows one user to authenticate on behalf of another user. I have no idea why on earth it supports that or why you'd practically want to use it, but it does support it. It calls this an authorization identity.