usr/src/man/man3pam/pam_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_AUTHENTICATE 3PAM "Jan 27, 2005"
   7 .SH NAME
   8 pam_authenticate \- perform authentication within the PAM framework
   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
  15
  16 \fBint\fR \fBpam_authenticate\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR);
  17 .fi
  18
  19 .SH DESCRIPTION
  20 .sp
  21 .LP
  22 The \fBpam_authenticate()\fR function is called to authenticate the current
  23 user. The user is usually required to enter a password or similar
  24 authentication token depending upon the authentication service configured
  25 within the system. The user in question should have been specified by a prior
  26 call to \fBpam_start()\fR or \fBpam_set_item()\fR.
  27 .sp
  28 .LP
  29 The following flags may be set in the \fIflags\fR field:
  30 .sp
  31 .ne 2
  32 .na
  33 \fB\fBPAM_SILENT\fR\fR
  34 .ad
  35 .RS 29n
  36 Authentication service should not generate any messages.
  37 .RE
  38
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fBPAM_DISALLOW_NULL_AUTHTOK\fR\fR
  43 .ad
  44 .RS 29n
  45 The authentication service should return  \fBPAM_AUTH_ERR\fR if the user has a
  46 null authentication token.
  47 .RE
  48
  49 .SH RETURN VALUES
  50 .sp
  51 .LP
  52 Upon successful completion,  \fBPAM_SUCCESS\fR is returned.  In addition to the
  53 error return values described in \fBpam\fR(3PAM), the following values may be
  54 returned:
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBPAM_AUTH_ERR\fR\fR
  59 .ad
  60 .RS 25n
  61 Authentication failure.
  62 .RE
  63
  64 .sp
  65 .ne 2
  66 .na
  67 \fB\fBPAM_CRED_INSUFFICIENT\fR\fR
  68 .ad
  69 .RS 25n
  70 Cannot access authentication data due to insufficient credentials.
  71 .RE
  72
  73 .sp
  74 .ne 2
  75 .na
  76 \fB\fBPAM_AUTHINFO_UNAVAIL\fR\fR
  77 .ad
  78 .RS 25n
  79 Underlying authentication service cannot retrieve authentication information.
  80 .RE
  81
  82 .sp
  83 .ne 2
  84 .na
  85 \fB\fBPAM_USER_UNKNOWN\fR\fR
  86 .ad
  87 .RS 25n
  88 User not known to the underlying authentication module.
  89 .RE
  90
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBPAM_MAXTRIES\fR\fR
  95 .ad
  96 .RS 25n
  97 An authentication service has maintained a retry count which has been reached.
  98 No further retries should be attempted.
  99 .RE
 100
 101 .SH ATTRIBUTES
 102 .sp
 103 .LP
 104 See \fBattributes\fR(5) for description of the following attributes:
 105 .sp
 106
 107 .sp
 108 .TS
 109 box;
 110 c | c
 111 l | l .
 112 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 113 _
 114 Interface Stability      Stable
 115 _
 116 MT-Level        MT-Safe with exceptions
 117 .TE
 118
 119 .SH SEE ALSO
 120 .sp
 121 .LP
 122 \fBpam\fR(3PAM), \fBpam_open_session\fR(3PAM), \fBpam_set_item\fR(3PAM),
 123 \fBpam_setcred\fR(3PAM), \fBpam_start\fR(3PAM), \fBlibpam\fR(3LIB),
 124 \fBattributes\fR(5)
 125 .SH NOTES
 126 .sp
 127 .LP
 128 In the case of authentication failures due to an incorrect username or
 129 password, it is the responsibility of the application to retry
 130 \fBpam_authenticate()\fR and to maintain the retry count. An authentication
 131 service module may implement an internal retry count and return an error
 132 \fBPAM_MAXTRIES\fR if the module does not want the application to retry.
 133 .sp
 134 .LP
 135 If the  \fBPAM\fR framework cannot load the authentication module, then it will
 136 return  \fBPAM_ABORT\fR. This indicates a serious failure, and  the application
 137 should not attempt to retry the authentication.
 138 .sp
 139 .LP
 140 For security reasons, the location of authentication failures is hidden from
 141 the user.   Thus, if several authentication services are stacked and a single
 142 service fails, \fBpam_authenticate()\fR requires that the user re-authenticate
 143 each of the services.
 144 .sp
 145 .LP
 146 A null authentication token in the authentication database will result in
 147 successful authentication unless \fBPAM_DISALLOW_NULL_AUTHTOK\fR was specified.
 148 In such cases, there will be no prompt to the user to enter an authentication
 149 token.
 150 .sp
 151 .LP
 152 The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
 153 multithreaded application uses its own  \fBPAM\fR handle.