usr/src/man/man5/pam_unix_cred.5

   1 '\" te
   2 .\"  Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PAM_UNIX_CRED 5 "Mar 9, 2005"
   7 .SH NAME
   8 pam_unix_cred \- PAM user credential authentication module for UNIX
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpam_unix_cred.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBpam_unix_cred\fR module implements \fBpam_sm_setcred\fR(3PAM). It
  19 provides functions that establish user credential information. It is a module
  20 separate from the \fBpam_unix_auth\fR(5) module to allow replacement of the
  21 authentication functionality independently from the credential functionality.
  22 .sp
  23 .LP
  24 The \fBpam_unix_cred\fR module must always be stacked along with whatever
  25 authentication module is used to ensure correct credential setting.
  26 .sp
  27 .LP
  28 Authentication service modules must implement both \fBpam_sm_authenticate()\fR
  29 and \fBpam_sm_setcred()\fR.
  30 .sp
  31 .LP
  32 \fBpam_sm_authenticate()\fR in this module always returns \fBPAM_IGNORE\fR.
  33 .sp
  34 .LP
  35 \fBpam_sm_setcred()\fR initializes the user's project, privilege sets and
  36 initializes or updates the user's audit context if it hasn't already been
  37 initialized. The following flags may be set in the flags field:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fBPAM_ESTABLISH_CRED\fR\fR
  42 .ad
  43 .br
  44 .na
  45 \fB\fBPAM_REFRESH_CRED\fR\fR
  46 .ad
  47 .br
  48 .na
  49 \fB\fBPAM_REINITIALIZE_CRED\fR\fR
  50 .ad
  51 .sp .6
  52 .RS 4n
  53 Initializes the user's project to the project specified in \fBPAM_RESOURCE\fR,
  54 or if \fBPAM_RESOURCE\fR is not specified, to the user's default project.
  55 Establishes the user's privilege sets.
  56 .sp
  57 If the audit context is not already initialized and auditing is configured,
  58 these flags cause the context to be initialized to that of the user specified
  59 in \fBPAM_AUSER\fR (if any) merged with the user specified in \fBPAM_USER\fR
  60 and host specified in \fBPAM_RHOST\fR. If \fBPAM_RHOST\fR is not specified,
  61 \fBPAM_TTY\fR specifies the local terminal name. Attributing audit to
  62 \fBPAM_AUSER\fR and merging \fBPAM_USER\fR is required for correctly
  63 attributing auditing when the system entry is performed by another user that
  64 can be identified as trustworthy.
  65 .sp
  66 If the audit context is already initialized, the \fBPAM_REINITIALIZE_CRED\fR
  67 flag merges the current audit context with that of the user specified in
  68 \fBPAM_USER\fR. \fBPAM_REINITIALIZE_CRED\fR is useful when a user is assuming a
  69 new identity, as with \fBsu\fR(1M).
  70 .RE
  71
  72 .sp
  73 .ne 2
  74 .na
  75 \fB\fBPAM_DELETE_CRED\fR\fR
  76 .ad
  77 .sp .6
  78 .RS 4n
  79 This flag has no effect and always returns \fBPAM_SUCCESS\fR.
  80 .RE
  81
  82 .sp
  83 .LP
  84 The following options are interpreted:
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBdebug\fR\fR
  89 .ad
  90 .RS 10n
  91 Provides \fBsyslog\fR(3C) debugging information at the \fBLOG_DEBUG\fR level.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBnowarn\fR\fR
  98 .ad
  99 .RS 10n
 100 Disables any warning messages.
 101 .RE
 102
 103 .SH ERRORS
 104 .sp
 105 .LP
 106 Upon successful completion of \fBpam_sm_setcred()\fR, \fBPAM_SUCCESS\fR is
 107 returned. The following error codes are returned upon error:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBPAM_CRED_UNAVAIL\fR\fR
 112 .ad
 113 .RS 20n
 114 Underlying authentication service cannot retrieve user credentials
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBPAM_CRED_EXPIRED\fR\fR
 121 .ad
 122 .RS 20n
 123 User credentials have expired
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBPAM_USER_UNKNOWN\fR\fR
 130 .ad
 131 .RS 20n
 132 User is unknown to the authentication service
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBPAM_CRED_ERR\fR\fR
 139 .ad
 140 .RS 20n
 141 Failure in setting user credentials
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBPAM_BUF_ERR\fR\fR
 148 .ad
 149 .RS 20n
 150 Memory buffer error
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBPAM_SYSTEM_ERR\fR\fR
 157 .ad
 158 .RS 20n
 159 System error
 160 .RE
 161
 162 .sp
 163 .LP
 164 The following values are returned from \fBpam_sm_authenticate()\fR:
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBPAM_IGNORE\fR\fR
 169 .ad
 170 .RS 14n
 171 Ignores this module regardless of the control flag
 172 .RE
 173
 174 .SH ATTRIBUTES
 175 .sp
 176 .LP
 177 See \fBattributes\fR(5) for descriptions of the following attributes:
 178 .sp
 179
 180 .sp
 181 .TS
 182 box;
 183 c | c
 184 l | l .
 185 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 186 _
 187 Interface Stability     Evolving
 188 _
 189 MT Level        MT-Safe with exceptions
 190 .TE
 191
 192 .SH SEE ALSO
 193 .sp
 194 .LP
 195 \fBssh\fR(1), \fBsu\fR(1M), \fBsettaskid\fR(2), \fBlibpam\fR(3LIB),
 196 \fBgetprojent\fR(3PROJECT), \fBpam\fR(3PAM), \fBpam_set_item\fR(3PAM),
 197 \fBpam_sm_authenticate\fR(3PAM), \fBsyslog\fR(3C),
 198 \fBsetproject\fR(3PROJECT),\fBpam.conf\fR(4), \fBnsswitch.conf\fR(4),
 199 \fBproject\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5),
 200 \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5),
 201 \fBpam_passwd_auth\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_account\fR(5),
 202 \fBpam_unix_session\fR(5), \fBprivileges\fR(5)
 203 .SH NOTES
 204 .sp
 205 .LP
 206 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
 207 multi-threaded application uses its own \fBPAM\fR handle.
 208 .sp
 209 .LP
 210 If this module is replaced, the audit context and credential may not be
 211 correctly configured.