"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id='pam_sm_authenticate'>

  <refmeta>

    <refentrytitle>pam_sm_authenticate</refentrytitle>

    <manvolnum>3</manvolnum>

    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>

  </refmeta>

  <refnamediv id="pam_sm_authenticate-name">

    <refname>pam_sm_authenticate</refname>

    <refpurpose>PAM service function for user authentication</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <funcsynopsis id='pam_sm_authenticate-synopsis'>

      <funcsynopsisinfo>#define PAM_SM_AUTH</funcsynopsisinfo>

      <funcsynopsisinfo>#include <security/pam_modules.h></funcsynopsisinfo>

      <funcprototype>

        <funcdef>int <function>pam_sm_authenticate</function></funcdef>

        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>

        <paramdef>int <parameter>flags</parameter></paramdef>

        <paramdef>int <parameter>argc</parameter></paramdef>

        <paramdef>const char **<parameter>argv</parameter></paramdef>

      </funcprototype>

    </funcsynopsis>

  </refsynopsisdiv>

  <refsect1 id='pam_sm_authenticate-description'>

    <title>DESCRIPTION</title>

    <para>

      The <function>pam_sm_authenticate</function> function is the service

      module's implementation of the

      <citerefentry>

        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry> interface.

    </para>

    <para>

      This function performs the task of authenticating the user.

    </para>

    <para>

       Valid flags, which may be logically OR'd with

       <emphasis>PAM_SILENT</emphasis>, are:

    </para>

    <variablelist>

      <varlistentry>

        <term>PAM_SILENT</term>

        <listitem>

           <para>

             Do not emit any messages.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_DISALLOW_NULL_AUTHTOK</term>

        <listitem>

          <para>

            Return <emphasis remap='B'>PAM_AUTH_ERR</emphasis> if the

            database of authentication tokens for this authentication

            mechanism has a <emphasis>NULL</emphasis> entry for the user.

            Without this flag, such a <emphasis>NULL</emphasis> token

            will lead to a success without the user being prompted.

          </para>

        </listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id="pam_sm_authenticate-return_values">

    <title>RETURN VALUES</title>

    <variablelist>

      <varlistentry>

        <term>PAM_AUTH_ERR</term>

        <listitem>

          <para>

            Authentication failure.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_CRED_INSUFFICIENT</term>

        <listitem>

          <para>

            For some reason the application does not have sufficient

            credentials to authenticate the user.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_AUTHINFO_UNAVAIL</term>

        <listitem>

          <para>

            The modules were not able to access the authentication

            information. This might be due to a network or hardware

            failure etc.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_SUCCESS</term>

        <listitem>

           <para>

             The authentication token was successfully updated.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_USER_UNKNOWN</term>

        <listitem>

          <para>

            The supplied username is not known to the authentication

            service.

          </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>PAM_MAXTRIES</term>

        <listitem>

          <para>

            One or more of the authentication modules has reached its

            limit of tries authenticating the user. Do not try again.

          </para>

        </listitem>

      </varlistentry>

    </variablelist>

  </refsect1>

  <refsect1 id='pam_sm_authenticate-see_also'>

    <title>SEE ALSO</title>

    <para>

      <citerefentry>

        <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry>,

      <citerefentry>

        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry>,

      <citerefentry>

        <refentrytitle>pam_sm_setcred</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry>,

      <citerefentry>

        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>

      </citerefentry>,

      <citerefentry>

        <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>

      </citerefentry>

    </para>

  </refsect1>

</refentry>