share/man/man5/pam_unix_auth.5

   1 '\" te
   2 .\" Copyright (c) 2008, 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_AUTH 5 "Apr 23, 2008"
   7 .SH NAME
   8 pam_unix_auth \- PAM authentication module for UNIX
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpam_unix_auth.so.1\fR
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBpam_unix_auth\fR module implements \fBpam_sm_authenticate()\fR, which
  19 provides functionality to the PAM authentication stack. It provides functions
  20 that use \fBcrypt\fR(3C) to verify that the password contained in the \fBPAM\fR
  21 item \fBPAM_AUTHTOK\fR is the correct password for the user specified in the
  22 item \fBPAM_USER\fR. If \fBPAM_REPOSITORY\fR is specified, then user's password
  23 is fetched from that repository. Otherwise, the default \fBnsswitch.conf\fR(4)
  24 repository is searched for that user.
  25 .sp
  26 .LP
  27 For accounts in the name services which support automatic account locking, the
  28 account may be configured to be automatically locked (see \fBuser_attr\fR(4)
  29 and \fBpolicy.conf\fR(4)) after multiple failed login attempts.  For accounts
  30 that are configured for automatic locking, if authentication failure is to be
  31 returned, the failed login counter is incremented upon each failure. If the
  32 number of successive failures equals or exceeds \fBRETRIES\fR as defined in
  33 \fBlogin\fR(1), the account is locked and \fBPAM_MAXTRIES\fR is returned.
  34 Currently, only the "files" repository (see \fBpasswd\fR(4) and
  35 \fBshadow\fR(4)) supports automatic account locking. A successful
  36 authentication by this module clears the failed login counter and reports the
  37 number of failed attempts since the last successful authentication.
  38 .sp
  39 .LP
  40 Authentication service modules must implement both \fBpam_sm_authenticate()\fR
  41 and \fBpam_sm_setcred()\fR. To allow the authentication portion of UNIX
  42 authentication to be replaced, \fBpam_sm_setcred()\fR in this module always
  43 returns \fBPAM_IGNORE\fR. This module should be stacked with
  44 \fBpam_unix_cred\fR(5) to ensure a successful return from
  45 \fBpam_setcred\fR(3PAM).
  46 .sp
  47 .LP
  48 The following options can be passed to the module:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBnowarn\fR\fR
  53 .ad
  54 .sp .6
  55 .RS 4n
  56 Turn off warning messages.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBserver_policy\fR\fR
  63 .ad
  64 .sp .6
  65 .RS 4n
  66 If the account authority for the user, as specified by \fBPAM_USER\fR, is a
  67 server, do not apply the UNIX policy from the \fBpasswd\fR entry in the name
  68 service switch.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBnolock\fR\fR
  75 .ad
  76 .sp .6
  77 .RS 4n
  78 Regardless of the automatic account locking setting for the account, do not
  79 lock the account, increment or clear the failed login count. The \fBnolock\fR
  80 option allows for exempting account locking on a per service basis.
  81 .RE
  82
  83 .SH ERRORS
  84 .sp
  85 .LP
  86 The following error codes are returned from \fBpam_sm_authenticate()\fR:
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBPAM_AUTH_ERR\fR\fR
  91 .ad
  92 .sp .6
  93 .RS 4n
  94 Authentication failure.
  95 .RE
  96
  97 .sp
  98 .ne 2
  99 .na
 100 \fB\fBPAM_BUF_ERR\fR\fR
 101 .ad
 102 .sp .6
 103 .RS 4n
 104 Memory buffer error.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fBPAM_IGNORE\fR\fR
 111 .ad
 112 .sp .6
 113 .RS 4n
 114 Ignores module, not participating in result.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBPAM_MAXTRIES\fR\fR
 121 .ad
 122 .sp .6
 123 .RS 4n
 124 Maximum number of retries exceeded.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBPAM_PERM_DENIED\fR\fR
 131 .ad
 132 .sp .6
 133 .RS 4n
 134 Permission denied.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBPAM_SUCCESS\fR\fR
 141 .ad
 142 .sp .6
 143 .RS 4n
 144 Successfully obtains authentication token.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBPAM_SYSTEM_ERR\fR\fR
 151 .ad
 152 .sp .6
 153 .RS 4n
 154 System error.
 155 .RE
 156
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBPAM_USER_UNKNOWN\fR\fR
 161 .ad
 162 .sp .6
 163 .RS 4n
 164 No account present for user.
 165 .RE
 166
 167 .sp
 168 .LP
 169 The following error codes are returned from \fBpam_sm_setcred()\fR:
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBPAM_IGNORE\fR\fR
 174 .ad
 175 .sp .6
 176 .RS 4n
 177 Ignores this module regardless of the control flag.
 178 .RE
 179
 180 .SH ATTRIBUTES
 181 .sp
 182 .LP
 183 See \fBattributes\fR(5) for descriptions of the following attributes:
 184 .sp
 185
 186 .sp
 187 .TS
 188 box;
 189 c | c
 190 l | l .
 191 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 192 _
 193 Interface Stability     Committed
 194 _
 195 MT Level        MT-Safe with exceptions
 196 .TE
 197
 198 .SH SEE ALSO
 199 .sp
 200 .LP
 201 \fBlogin\fR(1), \fBpasswd\fR(1), \fBuseradd\fR(8), \fBusermod\fR(8),
 202 \fBroleadd\fR(8), \fBrolemod\fR(8), \fBcrypt\fR(3C), \fBlibpam\fR(3LIB),
 203 \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_setcred\fR(3PAM),
 204 \fBsyslog\fR(3C), \fBpam.conf\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4),
 205 \fBnsswitch.conf\fR(4), \fBshadow\fR(4), \fBuser_attr\fR(4),
 206 \fBattributes\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
 207 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5), \fBpam_passwd_auth\fR(5),
 208 \fBpam_unix_account\fR(5), \fBpam_unix_session\fR(5)
 209 .SH NOTES
 210 .sp
 211 .LP
 212 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
 213 multi-threaded application uses its own \fBPAM\fR handle.
 214 .sp
 215 .LP
 216 The \fBpam_unix\fR(5) module is no longer supported. Similar functionality is
 217 provided by \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5),
 218 \fBpam_authtok_store\fR(5), \fBpam_dhkeys\fR(5),
 219 \fBpam_passwd_auth\fR(5), \fBpam_setcred\fR(3PAM), \fBpam_unix_account\fR(5),
 220 \fBpam_unix_cred\fR(5), \fBpam_unix_session\fR(5).
 221 .sp
 222 .LP
 223 If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
 224 not recognize the type, the service module does not process any information,
 225 and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
 226 not set, a service module performs its default action.