libsasl(5)

NAME

libsasl - authentication library

SYNOPSIS

Cyrus SASL library handling communication between an application and the Cyrus SASL authentication framework.

Description

This document describes generic configuration options for the Cyrus SASL authentication library FClibsaslF[0].

The library handles communication between an application and the Cyrus SASL authentication framework. Both exchange information before FClibsaslF[0] can start offering authentication services for the application.

The application, among other data, sends the FCservice_nameF[0]. The service name is the services name as specified by IANA. SMTP servers, for example, send FCsmtpF[0] as FCservice_nameF[0]. This information is handed over by FClibsaslF[0] e.g. when Kerberos or PAM authentication takes place.

Configuration options in general are read either from a file or passed by the application using FClibsaslF[0] during library initialization.

File-Based configuration

When an application (server) starts, it initializes the FClibsaslF[0] library. The application passes FCapp_nameF[0] (application name) to the SASL library. Its value is used to construct the name of the application specific SASL configuration file. The Cyrus SASL sample-server, for example, sends FCsampleF[0] as FCapp_nameF[0]. Using this value the SASL library will search the configuration directories for a file named FCsample.confF[0] and read configuration options from it.

Application-Based Configuration

Configuration options for FClibsaslF[0] are written down together with application specific options in the applications configuration file. The application reads them and passes them over to FClibsaslF[0] when it loads the library.

Configuration Syntax

The general format of Cyrus SASL configuration file is as follows:

Configuration options

Configuration options are written each on a single physical line. Parameter and value must be separated by a colon and a single whitespace:

FCparameter: valueF[0]

Important

There must be no trailing whitespace after the value or Cyrus SASL will fail to apply the value appropriately!

Comments, Empty lines and whitespace-only lines

Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a ‘#’.

Options

There are generic options and options specific to the password verification service or auxiliary property plugin chosen by the administrator. Such specific options are documented in manuals listed in libsasl(5).

The following configuration parameters are generic configuration options:

FCauthdaemond_pathF[0] (default: FC/dev/nullF[0])

Path to Courier MTA authdaemond's unix socket. Only applicable when FCpwcheck_methodF[0] is set to FCauthdaemondF[0].

FCauto_transitionF[0]: (default: FCnoF[0])

Automatically transition users to other mechanisms when they do a successful plaintext authentication and if an auxprop plugin is used.

Important

This option does not apply to the ldapdb(5) plugin. It is a read-only plugin.

FCnoF[0]

Do not transition users to other mechanisms.

FCnoplainF[0]

Transition users to other mechanisms, but write non-plaintext secrets only.

FCyesF[0]

Transition users to other mechanisms.

Note

The only mechanisms (as currently implemented) which don't use plaintext secrets are OTP and SRP.

FCauxprop_pluginF[0]: (default: empty)

A whitespace-separated list of one or more auxiliary plugins used if the FCpwcheck_methodF[0] parameter specifies FCauxpropF[0] as an option. Plugins will be queried in list order. If no plugin is specified, all available plugins will be queried.

FCldapdbF[0]

Specify FCldapdbF[0] to use the Cyrus SASL ldapdb(5) plugin.

FCsasldbF[0]

Specify FCsasldbF[0] to use the Cyrus SASL sasldb(5) plugin.

FCsqlF[0]

Specify FCsqlF[0] to use the Cyrus SASL sql(5) plugin.

FClog_levelF[0]: (default: FC1F[0])

Specifies a numeric log level. Available log levels are:

FC0F[0]

Don't log anything

FC1F[0]

Log unusual errors

FC2F[0]

Log all authentication failures

FC3F[0]

Log non-fatal warnings

FC4F[0]

More verbose than 3

FC5F[0]

More verbose than 4

FC6F[0]

Traces of internal protocols

FC7F[0]

Traces of internal protocols, including passwords

Important

Cyrus SASL sends log messages to the application that runs it. The application decides if it forwards such messages to the sysklogd(8) service, to which FCfacilityF[0] they are sent and which FCpriorityF[0] is given to the message.

FCmech_listF[0]: (default: empty)

The optional FCmech_listF[0] parameter specifies a whitespace-separated list of one or more mechanisms allowed for authentication.

FCpwcheck_methodF[0]: (default: FCauxpropF[0])

A whitespace-separated list of one or more mechanisms. Cyrus SASL provides the following mechanisms:

FCauthdaemondF[0]

Configures Cyrus SASL to contact the Courier MTA authdaemond(8) password verification service for password verification.

FCalwaystrueF[0]

Lets the pwcheck succeed always.

FCauxpropF[0]

Cyrus SASL will use its own plugin infrastructure to verify passwords. The FCauxprop_pluginF[0] parameter controls which plugins will be used.

FCpwcheckF[0]

Verify passwords using the Cyrus SASL pwcheck(8) password verification service. The pwcheck daemon is considered deprecated and should not be used anymore. Use the saslauthd password verification service instead.

FCsaslauthdF[0]

Verify passwords using the Cyrus SASL saslauthd(8) password verification service.

FCsaslauthd_pathF[0]: (default: empty)

Path to saslauthd(8) run directory (including the FC/muxF[0] named pipe)

See also

authdaemond(5), ldapdb(5), libsasl(5), saslauthd(8), saslauthd.conf(5), saslpasswd2(5), sasldblistusers2(5), sasldb(5), sql(5)

Author

This manual was written for the Debian distribution because the original program does not have a manual page. Parts of the documentation have been taken from the Cyrus SASL's FCoptions.htmlF[0].

Patrick Ben Koetter
<[email protected][0]>