<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='pam_sm_chauthtok'>
  <refmeta>
    <refentrytitle>pam_sm_chauthtok</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_sm_chauthtok-name">
    <refname>pam_sm_chauthtok</refname>
    <refpurpose>PAM service function for authentication token management</refpurpose>
  </refnamediv>

<!-- body begins here -->

  <refsynopsisdiv>
    <funcsynopsis id='pam_sm_chauthtok-synopsis'>
      <funcsynopsisinfo>#define PAM_SM_PASSWORD</funcsynopsisinfo>
      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>PAM_EXTERN int <function>pam_sm_chauthtok</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_chauthtok-description'>
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_sm_chauthtok</function> function is the service
      module's implementation of the
      <citerefentry>
        <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry> interface.
    </para>
    <para>
      This function is used to (re-)set the authentication token of 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_CHANGE_EXPIRED_AUTHTOK</term>
        <listitem>
          <para>
            This argument indicates to the module that the users
            authentication token (password) should only be changed if 
            it has expired. This flag is optional and 
            <emphasis>must</emphasis> be combined with one of the 
            following two flags. Note, however, the following two options 
            are <emphasis>mutually exclusive</emphasis>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_PRELIM_CHECK</term>
        <listitem>
          <para>
            This indicates that the modules are being probed as to 
            their ready status for altering the user's authentication 
            token. If the module requires access to another system over 
            some network it should attempt to verify it can connect to 
            this system on receiving this flag. If a module cannot establish 
            it is ready to update the user's authentication token it should 
            return <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, this
            information will be passed back to the application.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_UPDATE_AUTHTOK</term>
        <listitem>
          <para>
            This informs the module that this is the call it should change
            the authorization tokens. If the flag is logically OR'd with
            <emphasis remap='B'>PAM_CHANGE_EXPIRED_AUTHTOK</emphasis>, the 
            token is only changed if it has actually expired.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
      The PAM library calls this function twice in succession. The first 
      time with <emphasis remap='B'>PAM_PRELIM_CHECK</emphasis> and then, 
      if the module does not return 
      <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, subsequently with
      <emphasis remap='B'>PAM_UPDATE_AUTHTOK</emphasis>. It is only on 
      the second call that the authorization token is (possibly) changed.
    </para>
  </refsect1>

  <refsect1 id="pam_sm_chauthtok-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_AUTHTOK_ERR</term>
        <listitem>
           <para>
             The module was unable to obtain the new authentication token.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHTOK_RECOVERY_ERR</term>
        <listitem>
          <para>
            The module was unable to obtain the old authentication token.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHTOK_LOCK_BUSY</term>
        <listitem>
          <para>
            Cannot change the authentication token since it is currently
            locked.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHTOK_DISABLE_AGING</term>
        <listitem>
          <para>
            Authentication token aging has been disabled.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_PERM_DENIED</term>
        <listitem>
          <para>
            Permission denied.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_TRY_AGAIN</term>
        <listitem>
          <para>
            Preliminary check was unsuccessful. Signals an immediate
            return to the application is desired.
          </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>
            User unknown to password service.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id='pam_sm_chauthtok-see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_sm_chauthtok</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>
