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