share/man/man3pam/pam.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 3PAM "Feb 22, 2005"
   7 .SH NAME
   8 pam \- PAM (Pluggable Authentication Module)
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <security/pam_appl.h>
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 The \fBPAM\fR framework, \fBlibpam\fR, consists of an interface library and
  20 multiple authentication  service modules.  The \fBPAM\fR interface library is
  21 the layer implementing the  Application Programming Interface ( \fBAPI\fR ).
  22 The authentication service modules are a set of dynamically loadable objects
  23 invoked by the \fBPAM\fR \fBAPI\fR to provide a particular type of user
  24 authentication. \fBPAM\fR gives system administrators the flexibility of
  25 choosing any authentication service available on the system to perform
  26 authentication. This framework also allows new authentication service modules
  27 to be plugged in and made available without modifying the applications.
  28 .sp
  29 .LP
  30 Refer to  \fISolaris Security for Developers Guide\fR for information about
  31 providing authentication, account management, session management, and password
  32 management through PAM modules.
  33 .SS "Interface Overview"
  34 .sp
  35 .LP
  36 The \fBPAM\fR library interface consists of six categories of functions,  the
  37 names for which all start with the prefix  \fBpam_\fR.
  38 .sp
  39 .LP
  40 The first category contains functions for establishing and terminating an
  41 authentication activity, which are \fBpam_start\fR(3PAM) and
  42 \fBpam_end\fR(3PAM). The functions \fBpam_set_data\fR(3PAM) and
  43 \fBpam_get_data\fR(3PAM) maintain module specific data. The functions
  44 \fBpam_set_item\fR(3PAM) and \fBpam_get_item\fR(3PAM) maintain state
  45 information. \fBpam_strerror\fR(3PAM) is the function that returns error status
  46 information.
  47 .sp
  48 .LP
  49 The second category contains the functions that authenticate an individual user
  50 and set the credentials of the user, \fBpam_authenticate\fR(3PAM) and
  51 \fBpam_setcred\fR(3PAM).
  52 .sp
  53 .LP
  54 The third category of  \fBPAM\fR interfaces is account management. The function
  55 \fBpam_acct_mgmt\fR(3PAM) checks for password aging and access-hour
  56 restrictions.
  57 .sp
  58 .LP
  59 Category four contains the functions that perform session management after
  60 access to the system has been granted. See \fBpam_open_session\fR(3PAM) and
  61 \fBpam_close_session\fR(3PAM)
  62 .sp
  63 .LP
  64 The fifth category consists of the function that changes authentication tokens,
  65 \fBpam_chauthtok\fR(3PAM). An authentication token is the object used to verify
  66 the identity of the user. In UNIX, an authentication token is a user's
  67 password.
  68 .sp
  69 .LP
  70 The sixth category of functions can be used to set values for \fBPAM\fR
  71 environment variables. See \fBpam_putenv\fR(3PAM), \fBpam_getenv\fR(3PAM), and
  72 \fBpam_getenvlist\fR(3PAM).
  73 .sp
  74 .LP
  75 The \fBpam_*(\|)\fR interfaces are implemented through the library
  76 \fBlibpam\fR. For each of the categories listed above, excluding categories one
  77 and six, dynamically loadable shared modules exist that provides the
  78 appropriate  service layer functionality upon demand. The functional entry
  79 points in the  service layer start with the  \fBpam_sm_\fR prefix.  The only
  80 difference between the \fBpam_sm_*(\|)\fR interfaces and their corresponding
  81 \fBpam_\fR interfaces is that all the \fBpam_sm_*(\|)\fR interfaces require
  82 extra parameters to pass service\(mispecific options to the shared modules.
  83 Refer to \fBpam_sm\fR(3PAM) for an overview of the \fBPAM\fR service module
  84 \fBAPIs.\fR
  85 .SS "Stateful Interface"
  86 .sp
  87 .LP
  88 A sequence of calls sharing a common set of state information is referred to as
  89 an authentication transaction.  An authentication  transaction begins with a
  90 call to \fBpam_start()\fR. \fBpam_start()\fR allocates space, performs various
  91 initialization activities, and assigns a \fBPAM\fR authentication handle to be
  92 used for subsequent calls to the library.
  93 .sp
  94 .LP
  95 After initiating an authentication transaction, applications can invoke
  96 \fBpam_authenticate()\fR to authenticate a particular user, and
  97 \fBpam_acct_mgmt()\fR to perform system entry management. For example, the
  98 application may want to determine if the user's  password has expired.
  99 .sp
 100 .LP
 101 If the user has been successfully authenticated, the application calls
 102 \fBpam_setcred()\fR to set any user credentials associated with the
 103 authentication service. Within one authentication transaction (between
 104 \fBpam_start()\fR and \fBpam_end()\fR), all calls to the  \fBPAM\fR interface
 105 should be made with the same authentication handle returned by
 106 \fBpam_start()\fR. This is necessary because certain service modules may store
 107 module-specific data in a handle that is intended for use by other modules. For
 108 example, during the call to \fBpam_authenticate()\fR, service modules may store
 109 data in the handle that is intended for use by \fBpam_setcred()\fR.
 110 .sp
 111 .LP
 112 To perform session management, applications call \fBpam_open_session()\fR.
 113 Specifically, the system may want to store  the total time for the session. The
 114 function \fBpam_close_session()\fR closes the current session.
 115 .sp
 116 .LP
 117 When necessary, applications can call \fBpam_get_item()\fR and
 118 \fBpam_set_item()\fR to access and to update specific authentication
 119 information. Such information may include the current username.
 120 .sp
 121 .LP
 122 To terminate an authentication transaction, the application simply calls
 123 \fBpam_end()\fR, which frees previously allocated space used to store
 124 authentication information.
 125 .SS "Application\(miAuthentication Service Interactive Interface"
 126 .sp
 127 .LP
 128 The authentication service in \fBPAM\fR does not communicate directly with the
 129 user; instead it relies on the application to perform all such interactions.
 130 The application passes a pointer to the function, \fBconv()\fR, along with any
 131 associated application data pointers, through a \fIpam_conv\fR structure to the
 132 authentication service when it initiates an authentication transaction, via a
 133 call to \fBpam_start()\fR. The service will then use the function,
 134 \fBconv()\fR, to prompt the user for data,  output error messages, and display
 135 text information. Refer to \fBpam_start\fR(3PAM) for more information.
 136 .SS "Stacking Multiple Schemes"
 137 .sp
 138 .LP
 139 The \fBPAM\fR architecture enables authentication by multiple authentication
 140 services through \fIstacking\fR. System entry applications, such as
 141 \fBlogin\fR(1), stack multiple service modules to authenticate users with
 142 multiple authentication services. The order in which authentication service
 143 modules are stacked is specified in the configuration file, \fBpam.conf\fR(4).
 144 A system administrator determines this ordering, and also determines  whether
 145 the same password can be used for all authentication services.
 146 .SS "Administrative Interface"
 147 .sp
 148 .LP
 149 The authentication library, \fB/usr/lib/libpam.so.1\fR, implements the
 150 framework interface. Various authentication services are  implemented by their
 151 own loadable modules whose paths are specified through the \fBpam.conf\fR(4)
 152 file.
 153 .SH RETURN VALUES
 154 .sp
 155 .LP
 156 The \fBPAM\fR functions may return one of the following generic values,  or one
 157 of the values defined in the specific man pages:
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fBPAM_SUCCESS\fR\fR
 162 .ad
 163 .RS 19n
 164 The function returned successfully.
 165 .RE
 166
 167 .sp
 168 .ne 2
 169 .na
 170 \fB\fBPAM_OPEN_ERR\fR\fR
 171 .ad
 172 .RS 19n
 173 \fBdlopen()\fR failed when dynamically loading a service module.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fBPAM_SYMBOL_ERR\fR\fR
 180 .ad
 181 .RS 19n
 182 Symbol not found.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fBPAM_SERVICE_ERR\fR\fR
 189 .ad
 190 .RS 19n
 191 Error in service module.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBPAM_SYSTEM_ERR\fR\fR
 198 .ad
 199 .RS 19n
 200 System error.
 201 .RE
 202
 203 .sp
 204 .ne 2
 205 .na
 206 \fB\fBPAM_BUF_ERR\fR\fR
 207 .ad
 208 .RS 19n
 209 Memory buffer error.
 210 .RE
 211
 212 .sp
 213 .ne 2
 214 .na
 215 \fB\fBPAM_CONV_ERR\fR\fR
 216 .ad
 217 .RS 19n
 218 Conversation failure.
 219 .RE
 220
 221 .sp
 222 .ne 2
 223 .na
 224 \fB\fBPAM_PERM_DENIED\fR\fR
 225 .ad
 226 .RS 19n
 227 Permission denied.
 228 .RE
 229
 230 .SH ATTRIBUTES
 231 .sp
 232 .LP
 233 See \fBattributes\fR(5) for description of the following attributes:
 234 .sp
 235
 236 .sp
 237 .TS
 238 box;
 239 c | c
 240 l | l .
 241 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 242 _
 243 MT Level        MT-Safe with exceptions
 244 .TE
 245
 246 .SH SEE ALSO
 247 .sp
 248 .LP
 249 \fBlogin\fR(1), \fBpam_authenticate\fR(3PAM), \fBpam_chauthtok\fR(3PAM),
 250 \fBpam_open_session\fR(3PAM), \fBpam_set_item\fR(3PAM),
 251 \fBpam_setcred\fR(3PAM), \fBpam_sm\fR(3PAM), \fBpam_start\fR(3PAM),
 252 \fBpam_strerror\fR(3PAM), \fBpam.conf\fR(4), \fBattributes\fR(5)
 253 .sp
 254 .LP
 255 \fISolaris Security for Developers Guide\fR
 256 .SH NOTES
 257 .sp
 258 .LP
 259 The interfaces in  \fBlibpam()\fR are MT-Safe only if each thread within the
 260 multithreaded application uses its own  \fBPAM\fR handle.