'\" 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_UNIX_CRED 7 "August 19, 2023"
.SH NAME
pam_unix_cred \- PAM user credential module for UNIX
.SH SYNOPSIS
.nf
\fBpam_unix_cred.so.1\fR
.fi

.SH DESCRIPTION
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(7) 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
.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(8).
.RE

.sp
.ne 2
.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
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level.
.RE

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

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

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

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

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

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

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

.sp
.LP
The following values are returned from \fBpam_sm_authenticate()\fR:
.sp
.ne 2
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 14n
Ignores this module regardless of the control flag
.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 syslog (3C),
.BR libpam (3LIB),
.BR pam (3PAM),
.BR pam_sm_authenticate (3PAM),
.BR pam_sm_setcred (3PAM),
.BR pam.conf (5),
.BR project (5),
.BR attributes (7),
.BR pam_unix_auth (7),
.BR pam_unix_session (7),
.BR su (8)
.SH NOTES
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.