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
|
'\" te
.\" Copyright (C) 2003, 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_AUTHTOK_GET 7 "April 9, 2016"
.SH NAME
pam_authtok_get \- authentication and password management module
.SH SYNOPSIS
.LP
.nf
\fBpam_authtok_get.so.1\fR
.fi
.SH DESCRIPTION
.LP
The \fBpam_authtok_get\fR service module provides password prompting
functionality to the PAM stack. It implements \fBpam_sm_authenticate()\fR and
\fBpam_sm_chauthtok()\fR, providing functionality to both the Authentication
Stack and the Password Management Stack.
.SS "Authentication Service"
.LP
The implementation of \fBpam_sm_authenticate\fR(3PAM) prompts the user name if
not set and then tries to get the authentication token from the pam handle. If
the token is not set, it then prompts the user for a password and stores it in
the \fBPAM\fR item \fBPAM_AUTHTOK\fR. This module is meant to be the first
module on an authentication stack where users are to authenticate using a
keyboard.
.SS "Password Management Service"
.LP
Due to the nature of the PAM Password Management stack traversal mechanism, the
\fBpam_sm_chauthtok\fR(3PAM) function is called twice. Once with the
\fBPAM_PRELIM_CHECK\fR flag, and one with the \fBPAM_UPDATE_AUTHTOK\fR flag.
.sp
.LP
In the first (\fBPRELIM\fR) invocation, the implementation of
\fBpam_sm_chauthtok\fR(3PAM) moves the contents of the \fBPAM_AUTHTOK\fR
(current authentication token) to \fBPAM_OLDAUTHTOK\fR, and subsequently
prompts the user for a new password. This new password is stored in
\fBPAM_AUTHTOK\fR.
.sp
.LP
If a previous module has set \fBPAM_OLDAUTHTOK\fR prior to the invocation of
pam_authtok_get, this module turns into a \fBNO-OP\fR and immediately returns
\fBPAM_SUCCESS\fR.
.sp
.LP
In the second (\fBUPDATE\fR) invocation, the user is prompted to Re-enter his
password. The pam_sm_chauthtok implementation verifies this reentered password
with the password stored in \fBPAM_AUTHTOK\fR. If the passwords match, the
module returns \fBPAM_SUCCESS\fR.
.sp
.LP
The following option can be passed to the module:
.sp
.ne 2
.na
\fBdebug\fR
.ad
.RS 9n
\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level
.RE
.SH ERRORS
.LP
The authentication service returns the following error codes:
.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 18n
Successfully obtains authentication token
.RE
.sp
.ne 2
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 18n
Fails to retrieve username, username is \fBNULL\fR or empty
.RE
.sp
.LP
The password management service returns the following error codes:
.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 19n
Successfully obtains authentication token
.RE
.sp
.ne 2
.na
\fB\fBPAM_AUTHTOK_ERR\fR\fR
.ad
.RS 19n
Authentication token manipulation error
.RE
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Interface Stability Evolving
_
MT Level MT-Safe with exceptions
.TE
.SH SEE ALSO
.LP
\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C),
\fBlibpam\fR(3LIB), \fBpam.conf\fR(5), \fBattributes\fR(7),
\fBpam_authtok_check\fR(7), pam_authtok_get(7), \fBpam_authtok_store\fR(7),
.BR pam_dhkeys (7),
.BR pam_passwd_auth (7),
.BR pam_unix_account (7),
.BR pam_unix_auth (7),
.BR pam_unix_session (7)
.SH NOTES
.LP
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
multi-threaded application uses its own PAM handle.
.sp
.LP
The \fBpam_unix\fR(7) module is no longer supported. Similar functionality is
provided by \fBpam_authtok_check\fR(7), \fBpam_authtok_get\fR(7),
\fBpam_authtok_store\fR(7), \fBpam_dhkeys\fR(7), \fBpam_passwd_auth\fR(7),
\fBpam_unix_account\fR(7), \fBpam_unix_auth\fR(7), and
\fBpam_unix_session\fR(7).
|
