JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris Security for Developers Guide
search filter icon
search icon

Document Information


1.  Oracle Solaris Security for Developers (Overview)

2.  Developing Privileged Applications

3.  Writing PAM Applications and Services

4.  Writing Applications That Use GSS-API

5.  GSS-API Client Example

6.  GSS-API Server Example

7.  Writing Applications That Use SASL

Introduction to Simple Authentication Security Layer (SASL)

SASL Library Basics

SASL Architecture

Security Mechanisms

SASL Security Strength Factor

Communication in SASL

SASL Connection Contexts

Steps in the SASL Cycle

libsasl Initialization

SASL Session Initialization

SASL Authentication

SASL Confidentiality and Integrity

Releasing SASL Sessions

libsasl Cleanup

SASL Example

SASL for Service Providers

SASL Plug-in Overview

Important Structures for SASL Plug-ins

Client Plug-ins

Server Plug-ins

User Canonicalization Plug-ins

Auxiliary Property (auxprop) Plug-ins

SASL Plug-in Development Guidelines

Error Reporting in SASL Plug-ins

Memory Allocation in SASL Plug-ins

Setting the SASL Negotiation Sequence

8.  Introduction to the Oracle Solaris Cryptographic Framework

9.  Writing User-Level Cryptographic Applications and Providers

10.  Using the Smart Card Framework

A.  Sample C-Based GSS-API Programs

B.  GSS-API Reference

C.  Specifying an OID

D.  Source Code for SASL Example

E.  SASL Reference Tables

F.  Packaging and Signing Cryptographic Providers



SASL for Service Providers

This section describes how to create plug-ins for providing mechanisms and other services to SASL applications.

Note - Due to export regulations, the Solaris SASL SPI does not support a security layer for non-Solaris client/server mechanism plug-ins. As a result, non-Solaris client/server mechanism plug-ins cannot offer integrity or privacy services. Solaris client/server mechanism plug-ins do not have this restriction.

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.

SASL Plug-in Development Guidelines

This section provides some additional pointers for developing SASL plug-ins.

Error Reporting in SASL Plug-ins

Good error reporting can help in tracking down authentication problems and in other debugging. Developers of plug-ins are encouraged to use the sasl_seterror() callback in the sasl_utils_t structure to supply detailed error information for a given connection.

Memory Allocation in SASL Plug-ins

The general rule for allocating memory in SASL is to free any memory that you have allocated when that memory is no longer needed. Following this rule improves performance and portability, and prevents memory leaks.

Setting the SASL Negotiation Sequence

A plug-in mechanism can set the order in which a client and server conduct a SASL conversation through the following flags:

If neither flag is set, the mechanism plug-in sets the order internally. In this case, the mechanism must check both the client and server for data that needs to be sent. Note that the situation where the client sends first is only possible when the protocol permits an initial response.

The case in which the server sends last requires that the plug-in set *serverout when the step function returns SASL_OK. Those mechanisms that never have the server send last must set *serverout to NULL. Those mechanisms that always have the server send last need to point *serverout to the success data.