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"
8 pam \- PAM (Pluggable Authentication Module)
12 #include <security/pam_appl.h>
13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
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.
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"
36 The \fBPAM\fR library interface consists of six categories of functions, the
37 names for which all start with the prefix \fBpam_\fR.
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
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).
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
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)
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
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).
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
85 .SS "Stateful Interface"
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.
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.
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.
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.
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.
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"
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"
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"
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)
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:
161 \fB\fBPAM_SUCCESS\fR\fR
164 The function returned successfully.
170 \fB\fBPAM_OPEN_ERR\fR\fR
173 \fBdlopen()\fR failed when dynamically loading a service module.
179 \fB\fBPAM_SYMBOL_ERR\fR\fR
188 \fB\fBPAM_SERVICE_ERR\fR\fR
191 Error in service module.
197 \fB\fBPAM_SYSTEM_ERR\fR\fR
206 \fB\fBPAM_BUF_ERR\fR\fR
215 \fB\fBPAM_CONV_ERR\fR\fR
218 Conversation failure.
224 \fB\fBPAM_PERM_DENIED\fR\fR
233 See \fBattributes\fR(5) for description of the following attributes:
241 ATTRIBUTE TYPE ATTRIBUTE VALUE
243 MT Level MT-Safe with exceptions
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)
255 \fISolaris Security for Developers Guide\fR
259 The interfaces in \fBlibpam()\fR are MT-Safe only if each thread within the
260 multithreaded application uses its own \fBPAM\fR handle.