'\" 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 "August 9, 2023"
.SH NAME
pam_authtok_get \- authentication and password management module
.SH SYNOPSIS
.nf
\fBpam_authtok_get.so.1\fR
.fi

.SH DESCRIPTION
The \fBpam_authtok_get\fR service module provides password prompting
functionality to the PAM stack. It implements \fBpam_sm_authenticate\fR(3PAM)
and \fBpam_sm_chauthtok\fR(3PAM), providing functionality to both the
Authentication Stack and the Password Management Stack.
.SS "Authentication Service"
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"
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
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
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
.BR pam (3PAM),
.BR pam_authenticate (3PAM),
.BR pam_sm_authenticate (3PAM),
.BR pam_sm_chauthtok (3PAM),
.BR syslog (3C),
.BR libpam (3LIB),
.BR pam.conf (5),
.BR attributes (7),
.BR pam_authtok_check (7),
.BR pam_authtok_store (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
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).