Communication in SASL

Applications communicate with libsasl through the libsasl API. libsasl can request additional information by means of callbacks that are registered by the application. Applications do not call plug-ins directly, only through libsasl. Plug-ins generally call the libsasl framework's plug-ins, which then call the application's callbacks. SASL plug-ins can also call the application directly, although the application does not know whether the call came from a plug-in or from libsasl.

Callbacks are useful in multiple areas, as follows.

• libsasl can use callbacks to get information that is needed to complete authentication.

• libsasl consumer applications can use callbacks to change search paths for plug-ins and configuration data, to verify files, and to change various default behaviors.

• Servers can use callbacks to change authorization policies, to supply different password verification methods, and to get password change information.

• Clients and servers can use callbacks to specify the language for error messages.

Applications register two sorts of callbacks: global and session. Additionally, libsasl defines a number of callback identifiers that are used to register for different sorts of callbacks. If a given type of callback is not registered, libsasl takes default action.

Session callbacks override global callbacks. If a session callback is specified for a given ID, the global callback is not called for that session. Some callbacks must be global, because these callbacks occur outside of sessions.

The following instances require global callbacks:

• Determination of search paths for plug-ins to load

• Verification of plug-ins

• Location of configuration data

• The logging of error messages

• Other global configuration of libsasl or its plug-ins

A SASL callback can be registered with a NULL callback function for a given SASL callback ID. The NULL callback function indicates that the client is equipped to supply the needed data. All SASL callback IDs start with the prefix SASL_CB_.

SASL provides the following callbacks for use by either a client or a server:

SASL_CB_GETOPT

Gets a SASL option. Options modify the behavior of libsasl(3LIB) and related plug-ins. Can be used by either a client or a server.

SASL_CB_LOG

Sets the logging function for libsasl and its plug-ins. The default behavior is to use syslog.

SASL_CB_GETPATH

Gets the colon-separated list of SASL plug-in search paths.

The default SASL plug-in search paths depend on the architecture as follows:

• 32-bit SPARC architecture: /usr/lib/sasl

• 32-bit x86 architecture: /usr/lib/sasl

• 64-bit SPARC architecture: /usr/lib/sasl/sparcv9

• x64 architecture: /usr/lib/sasl/amd64

SASL_CB_GETCONF

Gets the path to the SASL server's configuration directory. The default is /etc/sasl.

SASL_CB_LANGUAGE

Specifies a comma-separated list of RFC 1766 language codes in order of preference, for client and server error messages and for client prompts. The default is i-default.

SASL_CB_VERIFYFILE

Verifies the configuration file and plug-in files.

SASL provides the following callbacks for use by clients only:

SASL_CB_USER

Gets the client user name. The user name is the same as the authorization ID. The LOGNAME environment variable is the default.

SASL_CB_AUTHNAME

Gets the client authentication name.

SASL_CB_PASS

Gets a client passphrase-based secret.

SASL_CB_ECHOPROMPT

Gets the result for a given challenge prompt. The input from the client can be echoed.

SASL_CB_NOECHOPROMPT

Gets the result for a given challenge prompt. The input from the client should not be echoed.

SASL_CB_GETREALM

Sets the realm to be used for authentication.

SASL provides the following callbacks for use by servers only:

SASL_CB_PROXY_POLICY

Checks that an authenticated user is authorized to act on behalf of the specified user. If this callback is not registered, then the authenticated user and the user to be authorized must be the same. If these IDs are not the same, then the authentication fails. Use the server application to take care of nonstandard authorization policies.

SASL_CB_SERVER_USERDB_CHECKPASS

Verifies a plain text password against the caller-supplied user database.

SASL_CB_SERVER_USERDB_SETPASS

Stores a plain text password in the user database

SASL_CB_CANON_USER

Calls an application-supplied user canonicalization function.

When the SASL library is first initialized, the server and client declare any necessary global callbacks. The global callbacks are available prior to and during the SASL sessions. Prior to initialization, callbacks perform such tasks as loading plug-ins, logging data, and reading configuration files. At the start of a SASL session, additional callbacks can be declared. Such callbacks can override global callbacks if necessary.