<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry>
  <refmeta>
    <refentrytitle>libsasl</refentrytitle>

    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>libsasl</refname>

    <refpurpose>authentication library</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para>Cyrus SASL library handling communication between an application and
    the Cyrus SASL authentication framework.</para>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>

    <para>This document describes generic configuration options for the Cyrus
    SASL authentication library <systemitem
    class="library">libsasl</systemitem>.</para>

    <para>The library handles communication between an application and the
    Cyrus SASL authentication framework. Both exchange information before
    <systemitem class="library">libsasl</systemitem> can start offering
    authentication services for the application.</para>

    <para>The application, among other data, sends the
    <parameter>service_name</parameter>. The service name is the services name
    as specified by IANA. SMTP servers, for example, send
    <option>smtp</option> as <parameter>service_name</parameter>. This
    information is handed over by <systemitem
    class="library">libsasl</systemitem> e.g. when Kerberos or PAM
    authentication takes place.</para>

    <para>Configuration options in general are read either from a file or
    passed by the application using <systemitem
    class="library">libsasl</systemitem> during library initialization.</para>

    <refsection>
      <title>File-Based configuration</title>

      <para>When an application (server) starts, it initializes the
      <systemitem class="library">libsasl</systemitem> library. The
      application passes <parameter>app_name</parameter> (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 <option>sample</option> as
      <parameter>app_name</parameter>. Using this value the SASL library will
      search the configuration directories for a file named
      <filename>sample.conf</filename> and read configuration options from
      it.</para>

      <note>
        <para>Consult the applications manual to determine what
        <parameter>app_name</parameter> it sends to the Cyrus SASL
        library.</para>
      </note>
    </refsection>

    <refsection>
      <title>Application-Based Configuration</title>

      <para>Configuration options for <systemitem
      class="library">libsasl</systemitem> are written down together with
      application specific options in the applications configuration file. The
      application reads them and passes them over to <systemitem
      class="library">libsasl</systemitem> when it loads the library.</para>

      <note>
        <para>An example for application-based configuration is the Cyrus IMAP
        server <systemitem class="daemon">imapd</systemitem>. SASL
        configuration is written to <filename>imapd.conf</filename> and passed
        to the SASL library when the <systemitem
        class="daemon">imapd</systemitem> server starts.</para>
      </note>
    </refsection>
  </refsection>

  <refsection>
    <title>Configuration Syntax</title>

    <para>The general format of Cyrus SASL configuration file is as
    follows:</para>

    <variablelist>
      <varlistentry>
        <term>Configuration options</term>

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

          <programlisting>parameter: value</programlisting>

          <important>
            <para>There must be no trailing whitespace after the value or
            Cyrus SASL will fail to apply the value appropriately!</para>
          </important>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Comments, Emtpy lines and whitespace-only lines</term>

        <listitem>
          <para>Empty lines and whitespace-only lines are ignored, as are
          lines whose first non-whitespace character is a
          <quote>#</quote>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Options</title>

    <para>There are generic options and options specific to the password
    verification service or auxiliary property plugin choosen by the
    administrator. Such specific options are documented in manuals listed in
    <xref linkend="seealso" />.</para>

    <para>The following configuration parameters are generic configuration
    options:</para>

    <variablelist>
      <varlistentry>
        <term><parameter>authdaemond_path</parameter> (default:
        <option>/dev/null</option>)</term>

        <listitem>
          <para>Path to Courier MTA authdaemond's unix socket. Only applicable
          when <parameter>pwcheck_method</parameter> is set to
          <option>authdaemond</option>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>auto_transition</parameter>: (default:
        <option>no</option>)</term>

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

          <important>
            <para>This option does not apply to the <citerefentry>
                <refentrytitle>ldapdb</refentrytitle>

                <manvolnum>5</manvolnum>
              </citerefentry> plugin. It is a read-only plugin.</para>
          </important>

          <variablelist>
            <varlistentry>
              <term><option>no</option></term>

              <listitem>
                <para>Do not transition users to other mechanisms.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>noplain</option></term>

              <listitem>
                <para>Transition users to other mechanisms, but write
                non-plaintext secrets only.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>yes</option></term>

              <listitem>
                <para>Transition users to other mechanisms.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <note>
            <para>The only mechanisms (as currently implemented) which don't
            use plaintext secrets are OTP and SRP.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>auxprop_plugin</parameter>: (default: empty)</term>

        <listitem>
          <para>A whitespace-separated list of one or more auxiliary plugins
          used if the <parameter>pwcheck_method</parameter> parameter
          specifies <option>auxprop</option> as an option. Plugins will be
          queried in list order. If no plugin is specified, all available
          plugins will be queried.</para>

          <variablelist>
            <varlistentry>
              <term><option>ldapdb</option></term>

              <listitem>
                <para>Specify <option>ldapdb</option> to use the Cyrus SASL
                <citerefentry>
                    <refentrytitle>ldapdb</refentrytitle>

                    <manvolnum>5</manvolnum>
                  </citerefentry> plugin.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>sasldb</option></term>

              <listitem>
                <para>Specify <option>sasldb</option> to use the Cyrus SASL
                <citerefentry>
                    <refentrytitle>sasldb</refentrytitle>

                    <manvolnum>5</manvolnum>
                  </citerefentry> plugin.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>sql</option></term>

              <listitem>
                <para>Specify <option>sql</option> to use the Cyrus SASL
                <citerefentry>
                    <refentrytitle>sql</refentrytitle>

                    <manvolnum>5</manvolnum>
                  </citerefentry> plugin.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>log_level</parameter>: (default:
        <option>1</option>)</term>

        <listitem>
          <para>Specifies a numeric log level. Available log levels
          are:</para>

          <variablelist>
            <varlistentry>
              <term><option>0</option></term>

              <listitem>
                <para>Don't log anything</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>1</option></term>

              <listitem>
                <para>Log unusual errors</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>2</option></term>

              <listitem>
                <para>Log all authentication failures</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>3</option></term>

              <listitem>
                <para>Log non-fatal warnings</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>4</option></term>

              <listitem>
                <para>More verbose than 3</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>5</option></term>

              <listitem>
                <para>More verbose than 4</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>6</option></term>

              <listitem>
                <para>Traces of internal protocols</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>7</option></term>

              <listitem>
                <para>Traces of internal protocols, including passwords</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <important>
            <para>Cyrus SASL sends log messages to the application that runs
            it. The application decides if it forwards such messages to the
            <citerefentry>
                <refentrytitle>sysklogd</refentrytitle>

                <manvolnum>8</manvolnum>
              </citerefentry> service, to which
            <parameter>facility</parameter> they are sent and which
            <parameter>priority</parameter> is given to the message.</para>
          </important>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>mech_list</parameter>: (default: empty)</term>

        <listitem>
          <para>The optional <parameter>mech_list</parameter> parameter
          specifies a whitespace-separated list of one or more mechanisms
          allowed for authentication.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>pwcheck_method</parameter>: (default:
        <option>auxprop</option>)</term>

        <listitem>
          <para>A whitespace-separated list of one or more mechanisms. Cyrus
          SASL provides the following mechanisms:</para>

          <variablelist>
            <varlistentry>
              <term><option>authdaemond</option></term>

              <listitem>
                <para>Configures Cyrus SASL to contact the Courier MTA
                <citerefentry>
                    <refentrytitle>authdaemond</refentrytitle>

                    <manvolnum>8</manvolnum>
                  </citerefentry> password verification service for password
                verification.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>alwaystrue</option></term>

              <listitem>
                <para>TODO</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>auxprop</option></term>

              <listitem>
                <para>Cyrus SASL will use its own plugin infrastructure to
                verify passwords. The
                <parameter><parameter>auxprop_plugin</parameter></parameter>
                parameter controls which plugins will be used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>pwcheck</option></term>

              <listitem>
                <para>Verify passwords using the Cyrus SASL <citerefentry>
                    <refentrytitle>pwcheck</refentrytitle>

                    <manvolnum>8</manvolnum>
                  </citerefentry> password verification service. The pwcheck
                daemon is considered deprecated and should not be used
                anymore. Use the saslauthd password verification service
                instead.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>saslauthd</option></term>

              <listitem>
                <para>Verify passwords using the Cyrus SASL <citerefentry>
                    <refentrytitle>saslauthd</refentrytitle>

                    <manvolnum>8</manvolnum>
                  </citerefentry> password verification service.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>saslauthd_path</parameter>: (default: empty)</term>

        <listitem>
          <para>Path to <citerefentry>
              <refentrytitle>saslauthd</refentrytitle>

              <manvolnum>8</manvolnum>
            </citerefentry> run directory (including the
          <filename>/mux</filename> named pipe)</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection id="seealso">
    <title>See also</title>

    <para><citerefentry>
        <refentrytitle>authdaemond</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>ldapdb</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>libsasl</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslauthd</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslauthd.conf</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>saslpasswd2</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sasldblistusers2</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sasldb</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>sql</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry></para>
  </refsection>

  <refsection>
    <title>Readme files</title>

    <para><filename>README.Debian</filename></para>
  </refsection>

  <refsection>
    <title>Author</title>

    <para>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
    <filename>options.html</filename>.</para>

    <para><address>Patrick Ben Koetter
<email>p@state-of-mind.de</email></address></para>
  </refsection>
</refentry>
