This document describes generic configuration options for the Cyrus SASL authentication library libsasl.
The library handles communication between an application and the Cyrus SASL authentication framework. Both exchange information before libsasl can start offering authentication services for the application.
The application, among other data, sends the service_name. The service name is the services name as specified by IANA. SMTP servers, for example, send smtp as service_name. This information is handed over by libsasl 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 libsasl during library initialization.
When an application (server) starts, it initializes the libsasl library. The application passes app_name (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 sample as app_name. Using this value the SASL library will search the configuration directories for a file named sample.conf and read configuration options from it.
Consult the applications manual to determine what app_name it sends to the Cyrus SASL library.
Configuration options for libsasl are written down together with application specific options in the applications configuration file. The application reads them and passes them over to libsasl when it loads the library.
An example for application-based configuration is the Cyrus IMAP server imapd. SASL configuration is written to imapd.conf and passed to the SASL library when the imapd server starts.
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:
- Comments, Emtpy lines and whitespace-only lines
- Empty lines and whitespace-only lines are ignored, as are lines whose first non-whitespace character is a “#”.
There are generic options and options specific to the password verification service or auxiliary property plugin choosen by the administrator.
The following configuration parameters are generic configuration options:
- authdaemond_path (default: /dev/null)
- Path to Courier MTA authdaemond's unix socket. Only applicable when pwcheck_method is set to authdaemond.
- auto_transition (default: no)
Automatically transition users to other mechanisms when they do a successful plaintext authentication and if an auxprop plugin is used.
When used in conjunction with the ldapdb 5 plugin the user RDN must exist and the schema must contain the attributes cmusaslsecretPLAIN, cmusaslsecretCRAM-MD5, cmusaslsecretDIGEST-MD5, cmusaslsecretOTP and cmusaslsecretSRP.
- Do not transition users to other mechanisms.
- Transition users to other mechanisms, but write non-plaintext secrets only.
- Transition users to other mechanisms.
The mechanisms OTP, SRP. GSSAPI and EXTERNAL don't use plaintext secrets.
- auxprop_plugin (default: empty)
A whitespace-separated list of one or more auxiliary plugins used if the pwcheck_method parameter specifies auxprop as an option. Plugins will be queried in list order. If no plugin is specified, all available plugins will be queried.
- Specify ldapdb to use the Cyrus SASL ldapdb 5 plugin.
- Specify sasldb to use the Cyrus SASL sasldb 5 plugin.
- Specify sql to use the Cyrus SASL sql 5 plugin.
- canon_user_plugin (default: empty)
- Specifies the name of the canon_user plugin libsasl should use.
- keytab (default: /etc/krb5.keytab)
- Specifies the location of the keytab file. This option is used only in combination with the GSSAPI mechanism.
- log_level (default: 1)
Specifies a numeric log level. Available log levels are:
- Don't log anything
- Log unusual errors
- Log all authentication failures
- Log non-fatal warnings
- More verbose than 3
- More verbose than 4
- Traces of internal protocols
Traces of internal protocols, including passwords
Cyrus SASL sends log messages to the application that runs it. The application decides if it forwards such messages to the syslog service, to which facility they are sent and which priority is given to the message.
- mech_list (default: empty)
- The optional mech_list parameter specifies a whitespace-separated list of one or more mechanisms allowed for authentication.
- ntlm_server (default: empty)
- This option specifies the hostname of a server (WinNT, Win2K, Samba, etc) to which authentication will be proxied if the client requested a NTLM based authentication session.
- ntlm_v2 (default: no)
- A client using libsasl can tell libsasl to generate NTLMv2 responses in communication with a server.
- opiekeys (default: /etc/opiekeys)
- Specifies a location where libsasl should look for the opiekeys file.
- otp_mda (default: md5)
- Sets the message digest algorithm for one-time passwords used by sasl_setpass. Available options are md4, md5 and sha1.
- pwcheck_method (default: auxprop)
A whitespace-separated list of one or more mechanisms. Cyrus SASL provides the following mechanisms:
- Configures Cyrus SASL to contact the Courier MTA authdaemond 8 password verification service for password verification.
This plugin always returns a user has been successfully authenticated.
This plugin must only be used for testing.
- Cyrus SASL will use its own plugin infrastructure to verify passwords. The auxprop parameter controls which plugins will be used.
- 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.
- Verify passwords using the Cyrus SASL saslauthd 8 password verification service.
- saslauthd_path (default: empty)
- Path to saslauthd 8 run directory (including the /mux named pipe)
- reauth_timeout (default: 0)
- Duration (minutes) that authentication info will be cached for a “fast reauth”. A value of 0 will disable reauth.
- srp_mda (default: sha1)
- Sets the message digest algorithm for SRP calculations. Available options are md5, sha1 and rmd160.
- srvtab (default: /etc/srvtab)
- Specifies the location of the srvtab file. This option is used only in combination with the KERBEROS_4 mechanism.