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 guide for SASL System Administrators 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.
The application is a client of the SASL library. It can be a client or server application (or both, in the case of a proxy). It takes care of the on-the-wire representation of the SASL negotiation, however it performs no analysis of the exchange itself. It relies on the judgment of the SASL library whether authentication has occurred or not. The application is also responsible for determining if the authenticated user may authorize as another user id (for more details on authentication and authorization identities and their differences, see the guide for SASL System Administrators).
Examples of applications are Cyrus IMAPd, OpenLDAP, Sendmail, Mutt, sieveshell, cyradm, and many others.
The SASL Glue Layer¶
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:
Loading of any plugins (more on these below)
Ascertaining necessary security properties from the application to aid in the choice of mechanism (or to limit the available mechanisms)
Listing of available plugins to the application (mostly used on the server side)
Choosing the best mechanism from a list of available mechanisms for a particular authentication attempt (client-side)
Routing the authentication (and in the case of a mechanism with a security layer, encrypted) data packets between the application and the chosen mechanism.
Providing information about the SASL negotiation back to the application (authenticated user, requested authorization identity, security strength of any negotiated security layer, and so on).
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
no. Details of available password verification services are
Finally, the glue code allows the mechanisms and applications access to
two special types of plugins, Auxiliary Property or
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
The Cyrus SASL architecture 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
Plugins: SASL Mechanisms¶
The simplest types of plugins to understand are those which provide SASL mechanisms, such as GSSAPI, PLAIN, SCRAM, 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. 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:
- Password Verification Mechanisms
For example, PLAIN. These receive a raw password from the remote and then pass it into the glue code for verification by a password verifier. These require the existence of an outside security layer to hide the otherwise plaintext password from people who might be snooping on the wire. These mechanisms do not require that the server have access to a plaintext (or plaintext-equivalent) version of the password.
- Shared Secret Mechanisms
For these mechanisms, such as OTP, SCRAM, and SRP, there is a shared secret between the server and client (e.g. a password). However, in this case the password itself does not travel on the wire. Instead, the client passes a server a token that proves that it knows the secret (without actually sending the secret across the wire). For these mechanisms, the server generally needs a plaintext equivalent of the secret to be in local storage (not true for SRP).
- Kerberos Mechanisms
Kerberos mechanisms use a trusted third party to authenticate the client. These mechanisms don’t require the server to share any secret information with the client, it is all performed through the Kerberos protocol.
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
Plugins: Auxiliary Property¶
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.
Plugins: Username Canonicalization¶
Username Canonicalization plugins are not widely used, however it may be useful to use as a hook if your site has specific requirements for how userids are presented to the applications.
Password Verification Services¶
As described above, the password verifiers take a username and plaintext
password, and say either
no. It is not possible
to use them to verify hashes that might be provided by the shared secret
Password verifiers are selected using the
SASL option. There are two main password verifiers provided with Cyrus SASL:
This uses an auxprop plugin to fetch the password and then compares it with the client-provided copy to make the determination.
This calls out to the
saslauthddaemon, which also ships with the distribution. The
saslauthddaemon has a number of modules of its own, which allow it to do verification of passwords in a variety of ways, including PAM, LDAP, against a Kerberos database, and so on. This is how you would want to, for example, use the data contained in
/etc/shadowto authenticate users.