--- name: "libsasl" section: "5" platform: "linux" package: "libsasl2-2" version: "2.1.28+dfsg1-9" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/libsasl" --- # libsasl(5) authentication library ## 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 FC**smtp**F\[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 FC**sample**F\[0\] as FCapp\_nameF\[0\]. Using this value the SASL library will search the configuration directories for a file named FC*sample.conf*F\[0\] and read configuration options from it. **Note** Consult the applications manual to determine what FCapp\_nameF\[0\] it sends to the Cyrus SASL library. ## 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. **Note** An example for application-based configuration is the Cyrus IMAP server FCimapdF\[0\]. SASL configuration is written to FC*imapd.conf*F\[0\] and passed to the SASL library when the FCimapdF\[0\] server starts. ## 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)](/libsasl/5.md). The following configuration parameters are generic configuration options: - FCauthdaemond\_pathF\[0\] (default: FC**/dev/null**F\[0\]) Path to Courier MTA authdaemond's unix socket. Only applicable when FCpwcheck\_methodF\[0\] is set to FC**authdaemond**F\[0\]. - FCauto\_transitionF\[0\]: (default: FC**no**F\[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. - FC**no**F\[0\] Do not transition users to other mechanisms. - FC**noplain**F\[0\] Transition users to other mechanisms, but write non-plaintext secrets only. - FC**yes**F\[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 FC**auxprop**F\[0\] as an option. Plugins will be queried in list order. If no plugin is specified, all available plugins will be queried. - FC**ldapdb**F\[0\] Specify FC**ldapdb**F\[0\] to use the Cyrus SASL **ldapdb**(5) plugin. - FC**sasldb**F\[0\] Specify FC**sasldb**F\[0\] to use the Cyrus SASL **sasldb**(5) plugin. - FC**sql**F\[0\] Specify FC**sql**F\[0\] to use the Cyrus SASL **sql**(5) plugin. - FClog\_levelF\[0\]: (default: FC**1**F\[0\]) Specifies a numeric log level. Available log levels are: - FC**0**F\[0\] Don't log anything - FC**1**F\[0\] Log unusual errors - FC**2**F\[0\] Log all authentication failures - FC**3**F\[0\] Log non-fatal warnings - FC**4**F\[0\] More verbose than 3 - FC**5**F\[0\] More verbose than 4 - FC**6**F\[0\] Traces of internal protocols - FC**7**F\[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)](/sysklogd/8.md) 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: FC**auxprop**F\[0\]) A whitespace-separated list of one or more mechanisms. Cyrus SASL provides the following mechanisms: - FC**authdaemond**F\[0\] Configures Cyrus SASL to contact the Courier MTA **authdaemond**(8) password verification service for password verification. - FC**alwaystrue**F\[0\] Lets the pwcheck succeed always. - FC**auxprop**F\[0\] Cyrus SASL will use its own plugin infrastructure to verify passwords. The FCauxprop\_pluginF\[0\] parameter controls which plugins will be used. - FC**pwcheck**F\[0\] Verify passwords using the Cyrus SASL [**pwcheck**(8)](/pwcheck/8.md) password verification service. The pwcheck daemon is considered deprecated and should not be used anymore. Use the saslauthd password verification service instead. - FC**saslauthd**F\[0\] Verify passwords using the Cyrus SASL [**saslauthd**(8)](/saslauthd/8.md) password verification service. - FCsaslauthd\_pathF\[0\]: (default: empty) Path to [**saslauthd**(8)](/saslauthd/8.md) run directory (including the FC*/mux*F\[0\] named pipe) ## See also **authdaemond**(5), **ldapdb**(5), [**libsasl**(5)](/libsasl/5.md), [**saslauthd**(8)](/saslauthd/8.md), **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 FC*options.html*F\[0\]. ``` Patrick Ben Koetter ```