summaryrefslogtreecommitdiff
path: root/doc/man/pam_chauthtok.3.xml
blob: d585e4c5b3d7d686fd329d274c32b0af8c87d644 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
<?xml version="1.0" encoding="ISO-8859-1"?>
<!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_chauthtok'>
  <refmeta>
    <refentrytitle>pam_chauthtok</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_chauthtok-name">
    <refname>pam_chauthtok</refname>
    <refpurpose>updating authentication tokens</refpurpose>
  </refnamediv>

<!-- body begins here -->

  <refsynopsisdiv id='pam_chauthtok-synopsis'>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>int <function>pam_chauthtok</function></funcdef>
        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
        <paramdef>int <parameter>flags</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1 id='pam_chauthtok-description'>
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_chauthtok</function> function is used to change the
      authentication token for a given user (as indicated by the state
      associated with the handle <emphasis>pamh</emphasis>).
    </para>
    <para>
      The <emphasis>pamh</emphasis> argument is an authentication 
      handle obtained by a prior call to pam_start().
      The flags argument is the binary or of zero or more of the
      following values:
    </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 modules that the users
            authentication token (password) should only be changed
            if it has expired.
            If this argument is not passed, the application requires
            that all authentication tokens are to be changed.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_chauthtok-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_AUTHTOK_ERR</term>
        <listitem>
           <para>
             A module was unable to obtain the new authentication token.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHTOK_RECOVERY_ERR</term>
        <listitem>
           <para>
             A module was unable to obtain the old authentication token.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_AUTHTOK_LOCK_BUSY</term>
        <listitem>
           <para>
             One or more of the modules was unable to 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 for at least
             one of the modules.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_PERM_DENIED</term>
        <listitem>
           <para>
             Permission denied.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             The authentication token was successfully updated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_TRY_AGAIN</term>
        <listitem>
           <para>
             Not all of the modules were in a position to update the
             authentication token(s). In such a case none of the user's
             authentication tokens are 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_chauthtok-see_also'>
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_get_item</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>