man > libsasl(5)

libsasl(5)                                                                                libsasl(5)

NAME
       libsasl - authentication library

SYNOPSIS
       Cyrus SASL library handling communication between an application and the Cyrus SASL authenti‐
       cation framework.

Description
       This  document  describes generic configuration options for the Cyrus SASL authentication li‐
       brary libsasl.

       The library handles communication between an application and the  Cyrus  SASL  authentication
       framework.  Both  exchange  information before libsasl can start offering authentication ser‐
       vices 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 infor‐
       mation 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 us‐
       ing libsasl during library initialization.

File-Based configuration
       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 configu‐
       ration directories for a file named sample.conf and read configuration options from it.
              Note

              Consult  the applications manual to determine what app_name it sends to the Cyrus SASL
              library.

Application-Based Configuration
       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.
              Note

              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.

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:

              parameter: value
              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-white‐
              space character is a ‘#’.

Options
       There are generic options and options specific to the password verification service or auxil‐
       iary  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:

       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.
              Important

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

              no     Do not transition users to other mechanisms.

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

              yes    Transition users to other mechanisms.
              Note

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

       auxprop_plugin: (default: empty)
              A whitespace-separated list  of  one  or  more  auxiliary  plugins  used  if  the  pw‐
              check_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.

              ldapdb Specify ldapdb to use the Cyrus SASL ldapdb(5) plugin.

              sasldb Specify sasldb to use the Cyrus SASL sasldb(5) plugin.

              sql    Specify sql to use the Cyrus SASL sql(5) plugin.

       log_level: (default: 1)
              Specifies a numeric log level. Available log levels are:

              0      Don't log anything

              1      Log unusual errors

              2      Log all authentication failures

              3      Log non-fatal warnings

              4      More verbose than 3

              5      More verbose than 4

              6      Traces of internal protocols

              7      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 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.

       pwcheck_method: (default: auxprop)
              A whitespace-separated list of one or more mechanisms. Cyrus SASL provides the follow‐
              ing mechanisms:

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

              alwaystrue
                     Lets the pwcheck succeed always.

              auxprop
                     Cyrus SASL will use its own plugin infrastructure to verify passwords. The aux‐
                     prop_plugin parameter controls which plugins will be used.

              pwcheck
                     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.

              saslauthd
                     Verify passwords using the Cyrus SASL saslauthd(8) password  verification  ser‐
                     vice.

       saslauthd_path: (default: empty)
              Path to saslauthd(8) run directory (including the /mux 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 op‐
       tions.html.

              Patrick Ben Koetter
              <p AT state-of-mind.de>

                                            15 April 2022                                 libsasl(5)