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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
<?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>#include <security/pam_modules.h></funcsynopsisinfo>
<funcprototype>
<funcdef>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 user's
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>
<para>
If the control value <emphasis>sufficient</emphasis> is used in
the password stack, the <emphasis>PAM_PRELIM_CHECK</emphasis> section
of the modules following that control value is not always executed.
</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>
|
