As the SASL library is a 'glue layer' between many different parts of the authentication system, there are a lot of different components that often cause confusion to users of the library who are trying to configure it for use on their system. This document will try to provide some structure to all of these components, though you will also need to read the System Administration to have a full understanding of how to install SASL on your system.
The first thing to realize is that there is a difference between SASL, the protocol, and Cyrus SASL, the library. The first is a specification that describes how authentication mechanisms can be plugged into an application protocol on the wire. The later is an implementation that aims to make this easier for application developers to integrate authentication mechanisms into their application in a generic way. It is quite possible to have an application that uses SASL (the specification) without using Cyrus SASL (the implementation).
The remainder of this document will refer to components of the Cyrus SASL implementation, though some of these will necessarily have a broader scope.
Examples of applications are Cyrus IMAPd, OpenLDAP, Sendmail, Mutt, sieveshell, cyradm, and many others.
The first component of the SASL library is affectionately called the "glue" layer. It takes care of ensuring that the application and the mechanisms can work together successfully. To this end, it does a variety of basic tasks:
The Cyrus SASL implementation also provides several other services to both its plugins and applications. Some of these are simply general utilities, such as MIME Base-64 encoding and decoding, and random number generation. Others are more specific to the task of authentication, such as providing password verification services. Such services are capable of taking a username and a plaintext password and saying "yes&quit; or "no". Details of available password verification services are discussed below.
Finally, the glue code allows the mechanisms and applications access to two special types of plugins, Auxiliary Property or "auxprop" plugins, which provide a simple database interface and can return properties about the user such as password, home directory, or mail routing address, and Username Canonicalization, which might provide site-specific ways to canonicalize a username or perform other tasks.
In the Cyrus SASL Implementation, the glue code is entirely contained within libsasl2.so (or libsasl2.a)
The Cyrus SASL architechure is very modular, using loadable modules for things such as the mechanism profiles and the database access done by the auxillary property plugins. This means that it is easy to limit what parts are loaded by a given application, and that third parties can write their own modules to provide services, just by adhering to the API description in saslplug.h.
The simplest types of plugins to understand are those which provide SASL mechanisms, such as CRAM-MD5, DIGEST-MD5, GSSAPI, PLAIN, SRP, and so on. These mechanisms take care of both server-side and client-side parts of the SASL negotiation. If the given mechanism supports a security layer (that is, makes guarantees about privacy or integrity of data after the negotiation is complete), the plugin provides that functionality as well.
SASL mechanisms are generally defined by the IETF standards process, however, some mechanisms are not (For example, NTLM). This is in contrast to the other types of plugins, which provide database and username canonicalization services to other plugins and thus aren't standardized in their behavior (they are specific to our implementation). Password verifiers are also an implementation detail (though saslauthd makes use of standards such as PAM and LDAP to perform that verification)
There are several types of mechanisms, in broad strokes we have:
Mechanism plugins are generally contained in a .so file that has a name similar to the mechanism's name. Though, in a static compilation they can also be a part of libsasl2.a
Auxiliary Property (or auxprop) plugins provide a database service for the glue layer (and through it, to the mechanisms and application). Cyrus SASL ships with two auxprop plugins: SASLdb and SQL. Though they can be use in much more generic ways, auxprop plugins are mostly only used by shared secret mechanisms (or by the auxprop password verify) to access the "userPassword" attribute. This provides a plaintext copy of the password that allows for authentication to take place.
Like the mechanism plugins, these are named similarly to the databases that they implement an interface for.
As described above, the password verifiers take a username and plaintext password, and say either "yes" or "no". It is not possible to use them to verify hashes that might be provided by the shared secret mechanisms.
Password verifiers are selected using the "pwcheck_method" SASL option. There are two main password verifiers provided with Cyrus SASL: