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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
'\" te
.\" Copyright (c) 1999, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_SM_CHAUTHTOK 3PAM "Mar 1, 2005"
.SH NAME
pam_sm_chauthtok \- service provider implementation for pam_chauthtok
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ...] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
#include <security/pam_appl.h>
#include <security/pam_modules.h>
\fBint\fR \fBpam_sm_chauthtok\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR, \fBint\fR \fIargc\fR,
\fBconst char **\fR\fIargv\fR);
.fi
.SH DESCRIPTION
.sp
.LP
In response to a call to \fBpam_chauthtok()\fR the \fBPAM\fR framework calls
pam_sm_chauthtok(3PAM) from the modules listed in the \fBpam.conf\fR(4) file.
The password management provider supplies the back-end functionality for this
interface function.
.sp
.LP
The \fBpam_sm_chauthtok()\fR function changes the authentication token
associated with a particular user referenced by the authentication handle
\fIpamh\fR.
.sp
.LP
The following flag may be passed to \fBpam_chauthtok()\fR:
.sp
.ne 2
.na
\fB\fBPAM_SILENT\fR\fR
.ad
.RS 30n
The password service should not generate any messages.
.RE
.sp
.ne 2
.na
\fB\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR\fR
.ad
.RS 30n
The password service should only update those passwords that have aged. If this
flag is not passed, the password service should update all passwords.
.RE
.sp
.ne 2
.na
\fB\fBPAM_PRELIM_CHECK\fR\fR
.ad
.RS 30n
The password service should only perform preliminary checks. No passwords
should be updated.
.RE
.sp
.ne 2
.na
\fB\fBPAM_NO_AUTHTOK_CHECK\fR\fR
.ad
.RS 30n
The password service should not perform conformance checks on the structure of
the password. Conformance checks do not apply to verification that the same
password was entered during both passes.
.RE
.sp
.ne 2
.na
\fB\fBPAM_UPDATE_AUTHTOK\fR\fR
.ad
.RS 30n
The password service should update passwords.
.RE
.sp
.LP
Note that \fBPAM_PRELIM_CHECK\fR and \fBPAM_UPDATE_AUTHTOK\fR cannot be set at
the same time.
.sp
.LP
Upon successful completion of the call, the authentication token of the user
will be ready for change or will be changed, depending upon the flag, in
accordance with the authentication scheme configured within the system.
.sp
.LP
The \fIargc\fR argument represents the number of module options passed in from
the configuration file \fBpam.conf\fR(4). The \fIargv\fR argument specifies the
module options, which are interpreted and processed by the password management
service. Please refer to the specific module man pages for the various
available \fIoptions\fR.
.sp
.LP
It is the responsibility of \fBpam_sm_chauthtok()\fR to determine if the new
password meets certain strength requirements. \fBpam_sm_chauthtok()\fR may
continue to re-prompt the user (for a limited number of times) for a new
password until the password entered meets the strength requirements.
.sp
.LP
Before returning, \fBpam_sm_chauthtok()\fR should call \fBpam_get_item()\fR
and retrieve both \fBPAM_AUTHTOK\fR and \fBPAM_OLDAUTHTOK\fR. If both are
\fINULL\fR, \fBpam_sm_chauthtok()\fR should set them to the new and old
passwords as entered by the user.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBPAM_SUCCESS\fR must be returned. The following
values may also be returned:
.sp
.ne 2
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.RS 29n
No permission.
.RE
.sp
.ne 2
.na
\fB\fBPAM_AUTHTOK_ERR\fR\fR
.ad
.RS 29n
Authentication token manipulation error.
.RE
.sp
.ne 2
.na
\fB\fBPAM_AUTHTOK_RECOVERY_ERR\fR\fR
.ad
.RS 29n
Old authentication token cannot be recovered.
.RE
.sp
.ne 2
.na
\fB\fBPAM_AUTHTOK_LOCK_BUSY\fR\fR
.ad
.RS 29n
Authentication token lock busy.
.RE
.sp
.ne 2
.na
\fB\fBPAM_AUTHTOK_DISABLE_AGING\fR\fR
.ad
.RS 29n
Authentication token aging disabled.
.RE
.sp
.ne 2
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 29n
User unknown to password service.
.RE
.sp
.ne 2
.na
\fB\fBPAM_TRY_AGAIN\fR\fR
.ad
.RS 29n
Preliminary check by password service failed.
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for description of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Interface Stability Stable
_
MT-Level MT-Safe with exceptions
.TE
.SH SEE ALSO
.sp
.LP
\fBping\fR(1M), \fBpam\fR(3PAM), \fBpam_chauthtok\fR(3PAM),
\fBpam_get_data\fR(3PAM), \fBpam_get_item\fR(3PAM), \fBpam_set_data\fR(3PAM),
\fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The \fBPAM\fR framework invokes the password services twice. The first time the
modules are invoked with the flag, \fBPAM_PRELIM_CHECK\fR. During this stage,
the password modules should only perform preliminary checks. For example, they
may \fBping\fR remote name services to see if they are ready for updates. If a
password module detects a transient error such as a remote name service
temporarily down, it should return \fBPAM_TRY_AGAIN\fR to the \fBPAM\fR
framework, which will immediately return the error back to the application. If
all password modules pass the preliminary check, the \fBPAM\fR framework
invokes the password services again with the flag, \fBPAM_UPDATE_AUTHTOK\fR.
During this stage, each password module should proceed to update the
appropriate password. Any error will again be reported back to application.
.sp
.LP
If a service module receives the flag \fBPAM_CHANGE_EXPIRED_AUTHTOK\fR, it
should check whether the password has aged or expired. If the password has aged
or expired, then the service module should proceed to update the password. If
the status indicates that the password has not yet aged or expired, then the
password module should return \fBPAM_IGNORE\fR.
.sp
.LP
If a user's password has aged or expired, a \fBPAM\fR account module could save
this information as state in the authentication handle, \fIpamh\fR, using
\fBpam_set_data()\fR. The related password management module could retrieve
this information using \fBpam_get_data()\fR to determine whether or not it
should prompt the user to update the password for this particular module.
.sp
.LP
The interfaces in \fBlibpam\fR are MT-Safe only if each thread within the
multithreaded application uses its own \fBPAM\fR handle.
.sp
.LP
If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
not recognize the type, the service module does not process any information,
and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
not set, a service module performs its default action.
|
