Oracle Solaris Security for Developers Guide

SASL Plug-in Overview

The SASL service provider interface (SPI) enables communication between plug-ins and the libsasl library. SASL plug-ins are typically implemented as shared libraries. A single shared library can one or more SASL plug-ins of different types. Plug-ins that are in shared libraries are opened dynamically by libsasl through the dlopen(3C) function.

Plug-ins can also be statically bound to an application that calls libsasl. These kinds of plug-ins are loaded through either the sasl_client_add_plugin() function or the sasl_server_add_plugin() function, depending on whether the application is a client or server.

A SASL plug-in in the Solaris operating system has the following requirements:

SASL plug-ins fall into four categories:

The sasl_client_init() function causes SASL clients to load any available client plug-ins. The sasl_server_init() function causes SASL servers to load the server, canonicalization, and auxprop plug-ins. All plug-ins are unloaded when sasl_done() is called.

To locate plug-ins, libsasl uses either the SASL_CB_GETPATH callback function or the default path. SASL_CB_GETPATH returns a colon-separated list of directories to be searched for plug-ins. If the SASL consumer specifies a SASL_CB_GETPATH callback, then libsasl uses the returned path for searching. Otherwise, the SASL consumer can use the default path that corresponds to the binary type:

As part of the loading process, libsasl calls the latest, supported version of the plug-in. The plug-in returns the version and a structure that describes the plug-in. If the version checks out, libsasl loads the plug-in. The current version number, SASL_UTILS_VERSION, is 4.

After a plug-in has been initialized, subsequent communication between the plug-in and libsasl takes place through structures that have to be established. Plug-ins use the sasl_utils_t structure to call libsasl. libsasl uses entry points in the following structures to communicate with plug-ins:

The source code for these structures can be found in the SASL header files. The structures are described in the following section.

Important Structures for SASL Plug-ins

Communication between libsasl and plug-ins is accomplished through the following structures:

Client Plug-ins

Client plug-ins are used to manage the client-side of a SASL negotiation. Client plug-ins are usually packaged with the corresponding server plug-ins. A client plug-in contains one or more client-side SASL mechanisms. Each SASL client mechanism supports authentication, and optionally integrity and confidentiality. Each mechanism provides information about that mechanism's capabilities:

Client plug-ins must export sasl_client_plug_init(). libsasl calls sasl_client_plug_init() to initialize the plug-in for the client. The plug-in returns a sasl_client_plug_t structure. The sasl_client_plug_t provides the following entry points for libsasl to call the mechanism:

Server Plug-ins

Server plug-ins are used to manage the server-side of a SASL negotiation. Server plug-ins are usually packaged with the corresponding client plug-ins. A server plug-in contains one or more server-side SASL mechanisms. Each SASL server mechanism supports authentication, and optionally integrity and confidentiality. Each mechanism provides information about that mechanism's capabilities:

Server plug-ins must export sasl_server_plug_init(). libsasl calls sasl_server_plug_init() to initialize the plug-in for the server. The plug-in returns a sasl_server_plug_t structure. The sasl_server_plug_t provides the following entry points for libsasl to call the mechanism:

User Canonicalization Plug-ins

A canonicalization plug-in provides support for alternate canonicalization of authentication and authorization names for both the client and server-side. The sasl_canonuser_plug_init() is used to load canonicalization plug-ins. A canonicalization plug-in has the following requirements:

User canonicalization plug-ins must export a sasl_canonuser_init() function. The sasl_canonuser_init() function must return sasl_canonuser_plug_t to establish the necessary entry points. User canonicalization plug-ins must implement at least one of the canon_user_client() or canon_user_server() members of the sasl_canonuser_plug_t structure.

Auxiliary Property (auxprop) Plug-ins

auxprop plug-ins provide support for the lookup of auxiliary properties for both authid and authzid for a SASL server. For example, an application might want to look up the user password for an internal authentication. The sasl_auxprop_plug_init() function is used to initialize auxprop plug-ins and returns the sasl_auxprop_plug_t structure.

To implement an auxprop plug-in successfully, the auxprop_lookup member of the sasl_auxprop_plug_t structure must be implemented. The auxprop_lookup() function is called after canonicalization of the user name, with the canonicalized user name. The plug-in can then do any lookups that are needed for the requested auxiliary properties.

Note –

Sun Microsystems, Inc. does not currently provide auxprop plug-ins.