usr/src/man/man3pam/pam_sm_authenticate.3pam

   1 '\" te
   2 .\" Copyright (c) 2005, 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_SM_AUTHENTICATE 3PAM "Jan 27, 2005"
   7 .SH NAME
   8 pam_sm_authenticate \- service provider implementation for pam_authenticate
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lpam\fR [ \fIlibrary\fR... ]
  13 #include <security/pam_appl.h>
  14 #include <security/pam_modules.h>
  15
  16
  17 \fBint\fR \fBpam_sm_authenticate\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR,
  18      \fBint\fR \fIargc\fR, \fBconst char **\fR\fIargv\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 In response to a call to \fBpam_authenticate\fR(3PAM), the  \fBPAM\fR framework
  25 calls \fBpam_sm_authenticate()\fR from the modules listed in the
  26 \fBpam.conf\fR(4) file. The authentication provider supplies the back-end
  27 functionality for this interface function.
  28 .sp
  29 .LP
  30 The \fBpam_sm_authenticate()\fR function is called to verify the identity of
  31 the current user. The user is usually required to enter a password or similar
  32 authentication token depending upon the authentication scheme configured within
  33 the system. The user in question is specified by a prior call to
  34 \fBpam_start()\fR, and is referenced by the authentication handle \fIpamh\fR.
  35 .sp
  36 .LP
  37 If the user is unknown to the authentication service, the service module should
  38 mask this error and continue to prompt the user for a password. It should then
  39 return the error, \fBPAM_USER_UNKNOWN\fR.
  40 .sp
  41 .LP
  42 The following flag may be passed in to \fBpam_sm_authenticate()\fR:
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fBPAM_SILENT\fR\fR
  47 .ad
  48 .RS 29n
  49 The authentication service should not generate any messages.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fBPAM_DISALLOW_NULL_AUTHTOK\fR\fR
  56 .ad
  57 .RS 29n
  58 The authentication service should return
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fBPAM_AUTH_ERR\fR\fR
  65 .ad
  66 .RS 29n
  67 The user has a null authentication token.
  68 .RE
  69
  70 .sp
  71 .LP
  72 The \fIargc\fR argument represents the number of module options passed in from
  73 the configuration file \fBpam.conf\fR(4). \fIargv\fR specifies the module
  74 options, which are interpreted and processed by the authentication service.
  75 Please refer to the specific module man pages for the various available
  76 \fIoptions\fR. If any unknown option is passed in, the module should log the
  77 error and ignore the option.
  78 .sp
  79 .LP
  80 Before returning, \fBpam_sm_authenticate()\fR should call \fBpam_get_item()\fR
  81 and retrieve \fBPAM_AUTHTOK\fR. If it has not been set before and the value is
  82 \fINULL\fR, \fBpam_sm_authenticate()\fR should set it to the password entered
  83 by the user using \fBpam_set_item()\fR.
  84 .sp
  85 .LP
  86 An authentication module may save the authentication status (success or reason
  87 for failure) as state in the authentication handle using
  88 \fBpam_set_data\fR(3PAM). This information is intended for use by
  89 \fBpam_setcred()\fR.
  90 .SH RETURN VALUES
  91 .sp
  92 .LP
  93 Upon successful completion,  \fBPAM_SUCCESS\fR must be returned. In addition,
  94 the following values may be returned:
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBPAM_MAXTRIES\fR\fR
  99 .ad
 100 .RS 25n
 101 Maximum number of authentication attempts exceeded.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBPAM_AUTH_ERR\fR\fR
 108 .ad
 109 .RS 25n
 110 Authentication failure.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBPAM_CRED_INSUFFICIENT\fR\fR
 117 .ad
 118 .RS 25n
 119 Cannot access authentication data due to insufficient credentials.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBPAM_AUTHINFO_UNAVAIL\fR\fR
 126 .ad
 127 .RS 25n
 128 Underlying authentication service can not retrieve authentication information.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBPAM_USER_UNKNOWN\fR\fR
 135 .ad
 136 .RS 25n
 137 User not known to underlying authentication module.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fBPAM_IGNORE\fR\fR
 144 .ad
 145 .RS 25n
 146 Ignore underlying authentication module regardless of whether the control flag
 147 is \fIrequired\fR,\fIoptional,\fR or \fIsufficient\fR1.
 148 .RE
 149
 150 .SH ATTRIBUTES
 151 .sp
 152 .LP
 153 See \fBattributes\fR(5) for description of the following attributes:
 154 .sp
 155
 156 .sp
 157 .TS
 158 box;
 159 c | c
 160 l | l .
 161 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 162 _
 163 Interface Stability      Stable
 164 _
 165 MT-Level        MT-Safe with exceptions
 166 .TE
 167
 168 .SH SEE ALSO
 169 .sp
 170 .LP
 171 \fBpam\fR(3PAM), \fBpam_authenticate\fR(3PAM), \fBpam_get_item\fR(3PAM),
 172 \fBpam_set_data\fR(3PAM), \fBpam_set_item\fR(3PAM), \fBpam_setcred\fR(3PAM),
 173 \fBpam_start\fR(3PAM), \fBlibpam\fR(3LIB), \fBpam.conf\fR(4),
 174 \fBattributes\fR(5)
 175 .SH NOTES
 176 .sp
 177 .LP
 178 Modules should not retry the authentication in the event of a failure.
 179 Applications handle authentication retries and maintain the retry count. To
 180 limit the number of retries, the module can return a \fBPAM_MAXTRIES\fR error.
 181 .sp
 182 .LP
 183 The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
 184 multithreaded application uses its own  \fBPAM\fR handle.
 185 .sp
 186 .LP
 187 If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is set and a service module does
 188 not recognize the type, the service module does not process any information,
 189 and returns \fBPAM_IGNORE\fR. If the \fBPAM_REPOSITORY\fR \fIitem_type\fR is
 190 not set, a service module performs its default action.