← Back to branch summary

~ubuntu-branches/ubuntu/natty/pam/natty-security

« back to all changes in this revision

Viewing changes to doc/man/pam_sm_chauthtok.3

  • Committer: Bazaar Package Importer
  • Author(s): Steve Langasek
  • Date: 2009-08-26 00:40:14 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20090826004014-qsd46mostuyljeqp
Tags: 1.1.0-1ubuntu1
* Merge from Debian, remaining changes:
  - debian/libpam-modules.postinst: Add PATH to /etc/environment if it's not
    present there or in /etc/security/pam_env.conf. (should send to Debian).
  - debian/libpam0g.postinst: only ask questions during update-manager when
    there are non-default services running.
  - debian/patches-applied/series: Ubuntu patches are as below ...
  - debian/patches-applied/ubuntu-no-error-if-missingok: add a new, magic
    module option 'missingok' which will suppress logging of errors by
    libpam if the module is not found.
  - debian/patches-applied/ubuntu-regression_fix_securetty: prompt for
    password on bad username.
  - debian/patches-applied/ubuntu-rlimit_nice_correction: Explicitly
    initialise RLIMIT_NICE rather than relying on the kernel limits.
  - Change Vcs-Bzr to point at the Ubuntu branch.
  - debian/local/common-password, debian/pam-configs/unix: switch from
    "md5" to "sha512" as password crypt default.
  - Make libpam-modules depend on base-files (>= 5.0.0ubuntu6), to ensure
    run-parts does the right thing in /etc/update-motd.d.
  - debian/patches-applied/pam_motd-legal-notice: display the contents of
    /etc/legal once, then set a flag in the user's homedir to prevent showing
    it again.
  - debian/local/common-{auth,account,password}.md5sums: include the
    Ubuntu-specific intrepid,jaunty md5sums for use during the
    common-session-noninteractive upgrade.
* Dropped changes, superseded upstream:
  - debian/patches-applied/ubuntu-fix_standard_types: Use standard u_int8_t
    type rather than __u8.
  - debian/patches-applied/ubuntu-user_defined_environment: Look at
    ~/.pam_environment too, with the same format as
    /etc/security/pam_env.conf.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/man/pam_sm_chauthtok.3
1
1
.\"     Title: pam_sm_chauthtok
2
 
.\"    Author: 
3
 
.\" Generator: DocBook XSL Stylesheets v1.73.1 <http://docbook.sf.net/>
4
 
.\"      Date: 04/16/2008
 
2
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
 
3
.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
 
4
.\"      Date: 03/02/2009
5
5
.\"    Manual: Linux-PAM Manual
6
6
.\"    Source: Linux-PAM Manual
 
7
.\"  Language: English
7
8
.\"
8
 
.TH "PAM_SM_CHAUTHTOK" "3" "04/16/2008" "Linux-PAM Manual" "Linux-PAM Manual"
 
9
.TH "PAM_SM_CHAUTHTOK" "3" "03/02/2009" "Linux-PAM Manual" "Linux-PAM Manual"
 
10
.\" -----------------------------------------------------------------
 
11
.\" * (re)Define some macros
 
12
.\" -----------------------------------------------------------------
 
13
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
14
.\" toupper - uppercase a string (locale-aware)
 
15
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
16
.de toupper
 
17
.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
 
18
\\$*
 
19
.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
 
20
..
 
21
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
22
.\" SH-xref - format a cross-reference to an SH section
 
23
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
24
.de SH-xref
 
25
.ie n \{\
 
26
.\}
 
27
.toupper \\$*
 
28
.el \{\
 
29
\\$*
 
30
.\}
 
31
..
 
32
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
33
.\" SH - level-one heading that works better for non-TTY output
 
34
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
35
.de1 SH
 
36
.\" put an extra blank line of space above the head in non-TTY output
 
37
.if t \{\
 
38
.sp 1
 
39
.\}
 
40
.sp \\n[PD]u
 
41
.nr an-level 1
 
42
.set-an-margin
 
43
.nr an-prevailing-indent \\n[IN]
 
44
.fi
 
45
.in \\n[an-margin]u
 
46
.ti 0
 
47
.HTML-TAG ".NH \\n[an-level]"
 
48
.it 1 an-trap
 
49
.nr an-no-space-flag 1
 
50
.nr an-break-flag 1
 
51
\." make the size of the head bigger
 
52
.ps +3
 
53
.ft B
 
54
.ne (2v + 1u)
 
55
.ie n \{\
 
56
.\" if n (TTY output), use uppercase
 
57
.toupper \\$*
 
58
.\}
 
59
.el \{\
 
60
.nr an-break-flag 0
 
61
.\" if not n (not TTY), use normal case (not uppercase)
 
62
\\$1
 
63
.in \\n[an-margin]u
 
64
.ti 0
 
65
.\" if not n (not TTY), put a border/line under subheading
 
66
.sp -.6
 
67
\l'\n(.lu'
 
68
.\}
 
69
..
 
70
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
71
.\" SS - level-two heading that works better for non-TTY output
 
72
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
73
.de1 SS
 
74
.sp \\n[PD]u
 
75
.nr an-level 1
 
76
.set-an-margin
 
77
.nr an-prevailing-indent \\n[IN]
 
78
.fi
 
79
.in \\n[IN]u
 
80
.ti \\n[SN]u
 
81
.it 1 an-trap
 
82
.nr an-no-space-flag 1
 
83
.nr an-break-flag 1
 
84
.ps \\n[PS-SS]u
 
85
\." make the size of the head bigger
 
86
.ps +2
 
87
.ft B
 
88
.ne (2v + 1u)
 
89
.if \\n[.$] \&\\$*
 
90
..
 
91
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
92
.\" BB/BE - put background/screen (filled box) around block of text
 
93
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
94
.de BB
 
95
.if t \{\
 
96
.sp -.5
 
97
.br
 
98
.in +2n
 
99
.ll -2n
 
100
.gcolor red
 
101
.di BX
 
102
.\}
 
103
..
 
104
.de EB
 
105
.if t \{\
 
106
.if "\\$2"adjust-for-leading-newline" \{\
 
107
.sp -1
 
108
.\}
 
109
.br
 
110
.di
 
111
.in
 
112
.ll
 
113
.gcolor
 
114
.nr BW \\n(.lu-\\n(.i
 
115
.nr BH \\n(dn+.5v
 
116
.ne \\n(BHu+.5v
 
117
.ie "\\$2"adjust-for-leading-newline" \{\
 
118
\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
 
119
.\}
 
120
.el \{\
 
121
\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
 
122
.\}
 
123
.in 0
 
124
.sp -.5v
 
125
.nf
 
126
.BX
 
127
.in
 
128
.sp .5v
 
129
.fi
 
130
.\}
 
131
..
 
132
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
133
.\" BM/EM - put colored marker in margin next to block of text
 
134
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
135
.de BM
 
136
.if t \{\
 
137
.br
 
138
.ll -2n
 
139
.gcolor red
 
140
.di BX
 
141
.\}
 
142
..
 
143
.de EM
 
144
.if t \{\
 
145
.br
 
146
.di
 
147
.ll
 
148
.gcolor
 
149
.nr BH \\n(dn
 
150
.ne \\n(BHu
 
151
\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
 
152
.in 0
 
153
.nf
 
154
.BX
 
155
.in
 
156
.fi
 
157
.\}
 
158
..
 
159
.\" -----------------------------------------------------------------
 
160
.\" * set default formatting
 
161
.\" -----------------------------------------------------------------
9
162
.\" disable hyphenation
10
163
.nh
11
164
.\" disable justification (adjust text to left margin only)
12
165
.ad l
13
 
.SH "NAME"
14
 
pam_sm_chauthtok - PAM service function for authentication token management
15
 
.SH "SYNOPSIS"
 
166
.\" -----------------------------------------------------------------
 
167
.\" * MAIN CONTENT STARTS HERE *
 
168
.\" -----------------------------------------------------------------
 
169
.SH "Name"
 
170
pam_sm_chauthtok \- PAM service function for authentication token management
 
171
.SH "Synopsis"
16
172
.sp
17
173
.ft B
 
174
.fam C
 
175
.ps -1
18
176
.nf
19
177
#define PAM_SM_PASSWORD
20
178
.fi
 
179
.fam
 
180
.ps +1
21
181
.ft
22
182
.sp
23
183
.ft B
 
184
.fam C
 
185
.ps -1
24
186
.nf
25
 
#include <security/pam_modules\.h>
 
187
#include <security/pam_modules\&.h>
26
188
.fi
 
189
.fam
 
190
.ps +1
27
191
.ft
28
 
.HP 32
 
192
.fam C
 
193
.HP \w'PAM_EXTERN\ int\ pam_sm_chauthtok('u
29
194
.BI "PAM_EXTERN int pam_sm_chauthtok(pam_handle_t\ *" "pamh" ", int\ " "flags" ", int\ " "argc" ", const\ char\ **" "argv" ");"
 
195
.fam
30
196
.SH "DESCRIPTION"
31
197
.PP
32
198
The
33
199
\fBpam_sm_chauthtok\fR
34
200
function is the service module\'s implementation of the
35
201
\fBpam_chauthtok\fR(3)
36
 
interface\.
 
202
interface\&.
37
203
.PP
38
 
This function is used to (re\-)set the authentication token of the user\.
 
204
This function is used to (re\-)set the authentication token of the user\&.
39
205
.PP
40
206
Valid flags, which may be logically OR\'d with
41
207
\fIPAM_SILENT\fR, are:
42
208
.PP
43
209
PAM_SILENT
44
210
.RS 4
45
 
Do not emit any messages\.
 
211
Do not emit any messages\&.
46
212
.RE
47
213
.PP
48
214
PAM_CHANGE_EXPIRED_AUTHTOK
49
215
.RS 4
50
 
This argument indicates to the module that the users authentication token (password) should only be changed if it has expired\. This flag is optional and
 
216
This argument indicates to the module that the users authentication token (password) should only be changed if it has expired\&. This flag is optional and
51
217
\fImust\fR
52
 
be combined with one of the following two flags\. Note, however, the following two options are
53
 
\fImutually exclusive\fR\.
 
218
be combined with one of the following two flags\&. Note, however, the following two options are
 
219
\fImutually exclusive\fR\&.
54
220
.RE
55
221
.PP
56
222
PAM_PRELIM_CHECK
57
223
.RS 4
58
 
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
59
 
\fBPAM_TRY_AGAIN\fR, this information will be passed back to the application\.
 
224
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
 
225
\fBPAM_TRY_AGAIN\fR, this information will be passed back to the application\&.
 
226
.sp
 
227
If the control value
 
228
\fIsufficient\fR
 
229
is used in the password stack, the
 
230
\fIPAM_PRELIM_CHECK\fR
 
231
section of the modules following that control value is not always executed\&.
60
232
.RE
61
233
.PP
62
234
PAM_UPDATE_AUTHTOK
63
235
.RS 4
64
 
This informs the module that this is the call it should change the authorization tokens\. If the flag is logically OR\'d with
65
 
\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR, the token is only changed if it has actually expired\.
 
236
This informs the module that this is the call it should change the authorization tokens\&. If the flag is logically OR\'d with
 
237
\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR, the token is only changed if it has actually expired\&.
66
238
.RE
67
239
.PP
68
 
The PAM library calls this function twice in succession\. The first time with
 
240
The PAM library calls this function twice in succession\&. The first time with
69
241
\fBPAM_PRELIM_CHECK\fR
70
242
and then, if the module does not return
71
243
\fBPAM_TRY_AGAIN\fR, subsequently with
72
 
\fBPAM_UPDATE_AUTHTOK\fR\. It is only on the second call that the authorization token is (possibly) changed\.
 
244
\fBPAM_UPDATE_AUTHTOK\fR\&. It is only on the second call that the authorization token is (possibly) changed\&.
73
245
.SH "RETURN VALUES"
74
246
.PP
75
247
PAM_AUTHTOK_ERR
76
248
.RS 4
77
 
The module was unable to obtain the new authentication token\.
 
249
The module was unable to obtain the new authentication token\&.
78
250
.RE
79
251
.PP
80
252
PAM_AUTHTOK_RECOVERY_ERR
81
253
.RS 4
82
 
The module was unable to obtain the old authentication token\.
 
254
The module was unable to obtain the old authentication token\&.
83
255
.RE
84
256
.PP
85
257
PAM_AUTHTOK_LOCK_BUSY
86
258
.RS 4
87
 
Cannot change the authentication token since it is currently locked\.
 
259
Cannot change the authentication token since it is currently locked\&.
88
260
.RE
89
261
.PP
90
262
PAM_AUTHTOK_DISABLE_AGING
91
263
.RS 4
92
 
Authentication token aging has been disabled\.
 
264
Authentication token aging has been disabled\&.
93
265
.RE
94
266
.PP
95
267
PAM_PERM_DENIED
96
268
.RS 4
97
 
Permission denied\.
 
269
Permission denied\&.
98
270
.RE
99
271
.PP
100
272
PAM_TRY_AGAIN
101
273
.RS 4
102
 
Preliminary check was unsuccessful\. Signals an immediate return to the application is desired\.
 
274
Preliminary check was unsuccessful\&. Signals an immediate return to the application is desired\&.
103
275
.RE
104
276
.PP
105
277
PAM_SUCCESS
106
278
.RS 4
107
 
The authentication token was successfully updated\.
 
279
The authentication token was successfully updated\&.
108
280
.RE
109
281
.PP
110
282
PAM_USER_UNKNOWN
111
283
.RS 4
112
 
User unknown to password service\.
 
284
User unknown to password service\&.
113
285
.RE
114
286
.SH "SEE ALSO"
115
287
.PP