'\" te
.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
.TH pam_authtok_get 5 "15 Jun 2011" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
pam_authtok_get \- authentication and password management module
.SH SYNOPSIS
.LP
.nf
\fBpam_authtok_get.so.1\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpam_authtok_get\fR service module provides password prompting funtionality 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"
.sp
.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"
.sp
.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 subsequentially 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
.mk
.na
\fBdebug\fR
.ad
.RS 9n
.rt  
\fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level
.RE

.SH ERRORS
.sp
.LP
The authentication service returns the following error codes:
.sp
.ne 2
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 18n
.rt  
Successfully obtains authentication token
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 18n
.rt  
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
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 19n
.rt  
Successfully obtains authentication token
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_AUTHTOK_ERR\fR\fR
.ad
.RS 19n
.rt  
Authentication token manipulation error
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBsyslog\fR(3C), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_session\fR(5)
.SH NOTES
.sp
.LP
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.