granicus.if.org Git - linux-pam/blob - doc/man/pam_sm_chauthtok.3.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
   4 <refentry id='pam_sm_chauthtok'>
   5   <refmeta>
   6     <refentrytitle>pam_sm_chauthtok</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_sm_chauthtok-name">
  12     <refname>pam_sm_chauthtok</refname>
  13     <refpurpose>PAM service function for authentication token management</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv>
  19     <funcsynopsis id='pam_sm_chauthtok-synopsis'>
  20       <funcsynopsisinfo>#define PAM_SM_PASSWORD</funcsynopsisinfo>
  21       <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  22       <funcprototype>
  23         <funcdef>PAM_EXTERN int <function>pam_sm_chauthtok</function></funcdef>
  24         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  25         <paramdef>int <parameter>flags</parameter></paramdef>
  26         <paramdef>int <parameter>argc</parameter></paramdef>
  27         <paramdef>const char **<parameter>argv</parameter></paramdef>
  28       </funcprototype>
  29     </funcsynopsis>
  30   </refsynopsisdiv>
  31
  32
  33   <refsect1 id='pam_sm_chauthtok-description'>
  34     <title>DESCRIPTION</title>
  35     <para>
  36       The <function>pam_sm_chauthtok</function> function is the service
  37       module's implementation of the
  38       <citerefentry>
  39         <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
  40       </citerefentry> interface.
  41     </para>
  42     <para>
  43       This function is used to (re-)set the authentication token of the user.
  44     </para>
  45     <para>
  46        Valid flags, which may be logically OR'd with
  47        <emphasis>PAM_SILENT</emphasis>, are:
  48     </para>
  49     <variablelist>
  50       <varlistentry>
  51         <term>PAM_SILENT</term>
  52         <listitem>
  53            <para>
  54              Do not emit any messages.
  55           </para>
  56         </listitem>
  57       </varlistentry>
  58       <varlistentry>
  59         <term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
  60         <listitem>
  61           <para>
  62             This argument indicates to the module that the users
  63             authentication token (password) should only be changed if
  64             it has expired. This flag is optional and
  65             <emphasis>must</emphasis> be combined with one of the
  66             following two flags. Note, however, the following two options
  67             are <emphasis>mutually exclusive</emphasis>.
  68           </para>
  69         </listitem>
  70       </varlistentry>
  71       <varlistentry>
  72         <term>PAM_PRELIM_CHECK</term>
  73         <listitem>
  74           <para>
  75             This indicates that the modules are being probed as to
  76             their ready status for altering the user's authentication
  77             token. If the module requires access to another system over
  78             some network it should attempt to verify it can connect to
  79             this system on receiving this flag. If a module cannot establish
  80             it is ready to update the user's authentication token it should
  81             return <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, this
  82             information will be passed back to the application.
  83           </para>
  84           <para>
  85              If the control value <emphasis>sufficient</emphasis> is used in
  86              the password stack, the <emphasis>PAM_PRELIM_CHECK</emphasis> section
  87              of the modules following that control value is not always executed.
  88           </para>
  89         </listitem>
  90       </varlistentry>
  91       <varlistentry>
  92         <term>PAM_UPDATE_AUTHTOK</term>
  93         <listitem>
  94           <para>
  95             This informs the module that this is the call it should change
  96             the authorization tokens. If the flag is logically OR'd with
  97             <emphasis remap='B'>PAM_CHANGE_EXPIRED_AUTHTOK</emphasis>, the
  98             token is only changed if it has actually expired.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102     </variablelist>
 103     <para>
 104       The PAM library calls this function twice in succession. The first
 105       time with <emphasis remap='B'>PAM_PRELIM_CHECK</emphasis> and then,
 106       if the module does not return
 107       <emphasis remap='B'>PAM_TRY_AGAIN</emphasis>, subsequently with
 108       <emphasis remap='B'>PAM_UPDATE_AUTHTOK</emphasis>. It is only on
 109       the second call that the authorization token is (possibly) changed.
 110     </para>
 111   </refsect1>
 112
 113   <refsect1 id="pam_sm_chauthtok-return_values">
 114     <title>RETURN VALUES</title>
 115     <variablelist>
 116       <varlistentry>
 117         <term>PAM_AUTHTOK_ERR</term>
 118         <listitem>
 119            <para>
 120              The module was unable to obtain the new authentication token.
 121           </para>
 122         </listitem>
 123       </varlistentry>
 124       <varlistentry>
 125         <term>PAM_AUTHTOK_RECOVERY_ERR</term>
 126         <listitem>
 127           <para>
 128             The module was unable to obtain the old authentication token.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132       <varlistentry>
 133         <term>PAM_AUTHTOK_LOCK_BUSY</term>
 134         <listitem>
 135           <para>
 136             Cannot change the authentication token since it is currently
 137             locked.
 138           </para>
 139         </listitem>
 140       </varlistentry>
 141       <varlistentry>
 142         <term>PAM_AUTHTOK_DISABLE_AGING</term>
 143         <listitem>
 144           <para>
 145             Authentication token aging has been disabled.
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149       <varlistentry>
 150         <term>PAM_PERM_DENIED</term>
 151         <listitem>
 152           <para>
 153             Permission denied.
 154           </para>
 155         </listitem>
 156       </varlistentry>
 157       <varlistentry>
 158         <term>PAM_TRY_AGAIN</term>
 159         <listitem>
 160           <para>
 161             Preliminary check was unsuccessful. Signals an immediate
 162             return to the application is desired.
 163           </para>
 164         </listitem>
 165       </varlistentry>
 166       <varlistentry>
 167         <term>PAM_SUCCESS</term>
 168         <listitem>
 169            <para>
 170              The authentication token was successfully updated.
 171           </para>
 172         </listitem>
 173       </varlistentry>
 174       <varlistentry>
 175         <term>PAM_USER_UNKNOWN</term>
 176         <listitem>
 177           <para>
 178             User unknown to password service.
 179           </para>
 180         </listitem>
 181       </varlistentry>
 182     </variablelist>
 183   </refsect1>
 184
 185   <refsect1 id='pam_sm_chauthtok-see_also'>
 186     <title>SEE ALSO</title>
 187     <para>
 188       <citerefentry>
 189         <refentrytitle>pam</refentrytitle><manvolnum>3</manvolnum>
 190       </citerefentry>,
 191       <citerefentry>
 192         <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 193       </citerefentry>,
 194       <citerefentry>
 195         <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
 196       </citerefentry>,
 197       <citerefentry>
 198         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 199       </citerefentry>,
 200       <citerefentry>
 201         <refentrytitle>PAM</refentrytitle><manvolnum>8</manvolnum>
 202       </citerefentry>
 203     </para>
 204   </refsect1>
 205 </refentry>