'\" te
.\"  Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
.TH pam_unix_cred 5 "9 Mar 2005" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
pam_unix_cred \- PAM user credential authentication module for UNIX
.SH SYNOPSIS
.LP
.nf
\fBpam_unix_cred.so.1\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpam_unix_cred\fR module implements \fBpam_sm_setcred\fR(3PAM). It provides functions that establish user credential information. It is a module separate from the \fBpam_unix_auth\fR(5) module to allow replacement of the authentication functionality independently from the credential functionality.
.sp
.LP
The \fBpam_unix_cred\fR module must always be stacked along with whatever authentication module is used to ensure correct credential setting.
.sp
.LP
Authentication service modules must implement both \fBpam_sm_authenticate()\fR and \fBpam_sm_setcred()\fR.
.sp
.LP
\fBpam_sm_authenticate()\fR in this module always returns \fBPAM_IGNORE\fR.
.sp
.LP
\fBpam_sm_setcred()\fR initializes the user's project, privilege sets and initializes or updates the user's audit context if it hasn't already been initialized. The following flags may be set in the flags field:
.sp
.ne 2
.mk
.na
\fB\fBPAM_ESTABLISH_CRED\fR\fR
.ad
.br
.na
\fB\fBPAM_REFRESH_CRED\fR\fR
.ad
.br
.na
\fB\fBPAM_REINITIALIZE_CRED\fR\fR
.ad
.sp .6
.RS 4n
Initializes the user's project to the project specified in \fBPAM_RESOURCE\fR, or if \fBPAM_RESOURCE\fR is not specified, to the user's default project. Establishes the user's privilege sets.
.sp
If the audit context is not already initialized and auditing is configured, these flags cause the context to be initialized to that of the user specified in \fBPAM_AUSER\fR (if any) merged with the user specified in \fBPAM_USER\fR and host specified in \fBPAM_RHOST\fR. If \fBPAM_RHOST\fR is not specified, \fBPAM_TTY\fR specifies the local terminal name. Attributing audit to \fBPAM_AUSER\fR and merging \fBPAM_USER\fR is required for correctly attributing auditing when the system entry is performed by another user that can be identified as trustworthy.
.sp
If the audit context is already initialized, the \fBPAM_REINITIALIZE_CRED\fR flag merges the current audit context with that of the user specified in \fBPAM_USER\fR. \fBPAM_REINITIALIZE_CRED\fR is useful when a user is assuming a new identity, as with \fBsu\fR(1M).
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_DELETE_CRED\fR\fR
.ad
.sp .6
.RS 4n
This flag has no effect and always returns \fBPAM_SUCCESS\fR.
.RE

.sp
.LP
The following options are interpreted:
.sp
.ne 2
.mk
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
.rt  
Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.mk
.na
\fB\fBnowarn\fR\fR
.ad
.RS 10n
.rt  
Disables any warning messages.
.RE

.SH ERRORS
.sp
.LP
Upon successful completion of \fBpam_sm_setcred()\fR, \fBPAM_SUCCESS\fR is returned. The following error codes are returned upon error:
.sp
.ne 2
.mk
.na
\fB\fBPAM_CRED_UNAVAIL\fR\fR
.ad
.RS 20n
.rt  
Underlying authentication service cannot retrieve user credentials
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_CRED_EXPIRED\fR\fR
.ad
.RS 20n
.rt  
User credentials have expired
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
.rt  
User is unknown to the authentication service
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_CRED_ERR\fR\fR
.ad
.RS 20n
.rt  
Failure in setting user credentials
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 20n
.rt  
Memory buffer error
.RE

.sp
.ne 2
.mk
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 20n
.rt  
System error
.RE

.sp
.LP
The following values are returned from \fBpam_sm_authenticate()\fR:
.sp
.ne 2
.mk
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 14n
.rt  
Ignores this module regardless of the control flag
.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
\fBssh\fR(1), \fBsu\fR(1M), \fBsettaskid\fR(2), \fBlibpam\fR(3LIB), \fBgetprojent\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_set_item\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBsyslog\fR(3C), \fBsetproject\fR(3PROJECT),\fBpam.conf\fR(4), \fBnsswitch.conf\fR(4), \fBproject\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_session\fR(5), \fBprivileges\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 \fBPAM\fR handle.
.sp
.LP
If this module is replaced, the audit context and credential may not be correctly configured.