granicus.if.org Git - linux-pam/blob - doc/man/pam_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_chauthtok'>
   5   <refmeta>
   6     <refentrytitle>pam_chauthtok</refentrytitle>
   7     <manvolnum>3</manvolnum>
   8     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
   9   </refmeta>
  10
  11   <refnamediv id="pam_chauthtok-name">
  12     <refname>pam_chauthtok</refname>
  13     <refpurpose>updating authentication tokens</refpurpose>
  14   </refnamediv>
  15
  16 <!-- body begins here -->
  17
  18   <refsynopsisdiv>
  19     <funcsynopsis id='pam_chauthtok-synopsis'>
  20       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  21       <funcprototype>
  22         <funcdef>int <function>pam_chauthtok</function></funcdef>
  23         <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  24         <paramdef>int <parameter>flags</parameter></paramdef>
  25       </funcprototype>
  26     </funcsynopsis>
  27   </refsynopsisdiv>
  28
  29
  30   <refsect1 id='pam_chauthtok-description'>
  31     <title>DESCRIPTION</title>
  32     <para>
  33       The <function>pam_chauthtok</function> function is used to change the
  34       authentication token for a given user (as indicated by the state
  35       associated with the handle <emphasis>pamh</emphasis>).
  36     </para>
  37     <para>
  38       The <emphasis>pamh</emphasis> argument is an authentication
  39       handle obtained by a prior call to pam_start().
  40       The flags argument is the binary or of zero or more of the
  41       following values:
  42     </para>
  43     <variablelist>
  44       <varlistentry>
  45         <term>PAM_SILENT</term>
  46         <listitem>
  47            <para>
  48              Do not emit any messages.
  49           </para>
  50         </listitem>
  51       </varlistentry>
  52       <varlistentry>
  53         <term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
  54         <listitem>
  55           <para>
  56             This argument indicates to the modules that the users
  57             authentication token (password) should only be changed
  58             if it has expired.
  59             If this argument is not passed, the application requires
  60             that all authentication tokens are to be changed.
  61           </para>
  62         </listitem>
  63       </varlistentry>
  64     </variablelist>
  65   </refsect1>
  66
  67   <refsect1 id="pam_chauthtok-return_values">
  68     <title>RETURN VALUES</title>
  69     <variablelist>
  70       <varlistentry>
  71         <term>PAM_AUTHTOK_ERR</term>
  72         <listitem>
  73            <para>
  74              A module was unable to obtain the new authentication token.
  75           </para>
  76         </listitem>
  77       </varlistentry>
  78       <varlistentry>
  79         <term>PAM_AUTHTOK_RECOVERY_ERR</term>
  80         <listitem>
  81            <para>
  82              A module was unable to obtain the old authentication token.
  83           </para>
  84         </listitem>
  85       </varlistentry>
  86       <varlistentry>
  87         <term>PAM_AUTHTOK_LOCK_BUSY</term>
  88         <listitem>
  89            <para>
  90              One or more of the modules was unable to change the
  91              authentication token since it is currently locked.
  92           </para>
  93         </listitem>
  94       </varlistentry>
  95       <varlistentry>
  96         <term>PAM_AUTHTOK_DISABLE_AGING</term>
  97         <listitem>
  98            <para>
  99              Authentication token aging has been disabled for at least
 100              one of the modules.
 101           </para>
 102         </listitem>
 103       </varlistentry>
 104       <varlistentry>
 105         <term>PAM_PERM_DENIED</term>
 106         <listitem>
 107            <para>
 108              Permission denied.
 109           </para>
 110         </listitem>
 111       </varlistentry>
 112       <varlistentry>
 113         <term>PAM_SUCCESS</term>
 114         <listitem>
 115            <para>
 116              The authentication token was successfully updated.
 117           </para>
 118         </listitem>
 119       </varlistentry>
 120       <varlistentry>
 121         <term>PAM_TRY_AGAIN</term>
 122         <listitem>
 123            <para>
 124              Not all of the modules were in a position to update the
 125              authentication token(s). In such a case none of the user's
 126              authentication tokens are updated.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130       <varlistentry>
 131         <term>PAM_USER_UNKNOWN</term>
 132         <listitem>
 133            <para>
 134              User unknown to password service.
 135           </para>
 136         </listitem>
 137       </varlistentry>
 138     </variablelist>
 139   </refsect1>
 140
 141   <refsect1 id='pam_chauthtok-see_also'>
 142     <title>SEE ALSO</title>
 143     <para>
 144       <citerefentry>
 145         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
 146       </citerefentry>,
 147       <citerefentry>
 148         <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
 149       </citerefentry>,
 150       <citerefentry>
 151         <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
 152       </citerefentry>,
 153       <citerefentry>
 154         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 155       </citerefentry>,
 156       <citerefentry>
 157         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 158       </citerefentry>,
 159       <citerefentry>
 160         <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
 161       </citerefentry>
 162     </para>
 163   </refsect1>
 164 </refentry>