1pam(3PAM) PAM Library Functions pam(3PAM)
2
6 pam - PAM (Pluggable Authentication Module)
7
9 #include <security/pam_appl.h>
10 cc [ flag... ] file ... -lpam [ library ... ]
11
14 The PAM framework, libpam, consists of an interface library and multi‐
15 ple authentication service modules. The PAM interface library is the
16 layer implementing the Application Programming Interface ( API ). The
17 authentication service modules are a set of dynamically loadable
18 objects invoked by the PAM API to provide a particular type of user
19 authentication. PAM gives system administrators the flexibility of
20 choosing any authentication service available on the system to perform
21 authentication. This framework also allows new authentication service
22 modules to be plugged in and made available without modifying the
23 applications.
24 Refer to Solaris Security for Developers Guide for information about
27 providing authentication, account management, session management, and
28 password management through PAM modules.
29 Interface Overview
31 The PAM library interface consists of six categories of functions, the
32 names for which all start with the prefix pam_.
33 The first category contains functions for establishing and terminating
36 an authentication activity, which are pam_start(3PAM) and
37 pam_end(3PAM). The functions pam_set_data(3PAM) and pam_get_data(3PAM)
38 maintain module specific data. The functions pam_set_item(3PAM) and
39 pam_get_item(3PAM) maintain state information. pam_strerror(3PAM) is
40 the function that returns error status information.
41 The second category contains the functions that authenticate an indi‐
44 vidual user and set the credentials of the user, pam_authenticate(3PAM)
45 and pam_setcred(3PAM).
46 The third category of PAM interfaces is account management. The func‐
49 tion pam_acct_mgmt(3PAM) checks for password aging and access-hour
50 restrictions.
51 Category four contains the functions that perform session management
54 after access to the system has been granted. See pam_open_session(3PAM)
55 and pam_close_session(3PAM)
56 The fifth category consists of the function that changes authentication
59 tokens, pam_chauthtok(3PAM). An authentication token is the object used
60 to verify the identity of the user. In UNIX, an authentication token is
61 a user's password.
62 The sixth category of functions can be used to set values for PAM envi‐
65 ronment variables. See pam_putenv(3PAM), pam_getenv(3PAM), and
66 pam_getenvlist(3PAM).
67 The pam_*() interfaces are implemented through the library libpam. For
70 each of the categories listed above, excluding categories one and six,
71 dynamically loadable shared modules exist that provides the appropriate
72 service layer functionality upon demand. The functional entry points in
73 the service layer start with the pam_sm_ prefix. The only difference
74 between the pam_sm_*() interfaces and their corresponding pam_ inter‐
75 faces is that all the pam_sm_*() interfaces require extra parameters to
76 pass service−specific options to the shared modules. Refer to
77 pam_sm(3PAM) for an overview of the PAM service module APIs.
78 Stateful Interface
80 A sequence of calls sharing a common set of state information is
81 referred to as an authentication transaction. An authentication
82 transaction begins with a call to pam_start(). pam_start() allocates
83 space, performs various initialization activities, and assigns a PAM
84 authentication handle to be used for subsequent calls to the library.
85 After initiating an authentication transaction, applications can invoke
88 pam_authenticate() to authenticate a particular user, and
89 pam_acct_mgmt() to perform system entry management. For example, the
90 application may want to determine if the user's password has expired.
91 If the user has been successfully authenticated, the application calls
94 pam_setcred() to set any user credentials associated with the authenti‐
95 cation service. Within one authentication transaction (between
96 pam_start() and pam_end()), all calls to the PAM interface should be
97 made with the same authentication handle returned by pam_start(). This
98 is necessary because certain service modules may store module-specific
99 data in a handle that is intended for use by other modules. For exam‐
100 ple, during the call to pam_authenticate(), service modules may store
101 data in the handle that is intended for use by pam_setcred().
102 To perform session management, applications call pam_open_session().
105 Specifically, the system may want to store the total time for the ses‐
106 sion. The function pam_close_session() closes the current session.
107 When necessary, applications can call pam_get_item() and pam_set_item()
110 to access and to update specific authentication information. Such
111 information may include the current username.
112 To terminate an authentication transaction, the application simply
115 calls pam_end(), which frees previously allocated space used to store
116 authentication information.
117 Application−Authentication Service Interactive Interface
119 The authentication service in PAM does not communicate directly with
120 the user; instead it relies on the application to perform all such
121 interactions. The application passes a pointer to the function, conv(),
122 along with any associated application data pointers, through a pam_conv
123 structure to the authentication service when it initiates an authenti‐
124 cation transaction, via a call to pam_start(). The service will then
125 use the function, conv(), to prompt the user for data, output error
126 messages, and display text information. Refer to pam_start(3PAM) for
127 more information.
128 Stacking Multiple Schemes
130 The PAM architecture enables authentication by multiple authentication
131 services through stacking. System entry applications, such as login(1),
132 stack multiple service modules to authenticate users with multiple
133 authentication services. The order in which authentication service
134 modules are stacked is specified in the configuration file,
135 pam.conf(4). A system administrator determines this ordering, and also
136 determines whether the same password can be used for all authentica‐
137 tion services.
138 Administrative Interface
140 The authentication library, /usr/lib/libpam.so.1, implements the frame‐
141 work interface. Various authentication services are implemented by
142 their own loadable modules whose paths are specified through the
143 pam.conf(4) file.
144
146 The PAM functions may return one of the following generic values, or
147 one of the values defined in the specific man pages:
148 PAM_SUCCESS The function returned successfully.
150 PAM_OPEN_ERR dlopen() failed when dynamically loading a service
153 module.
154 PAM_SYMBOL_ERR Symbol not found.
157 PAM_SERVICE_ERR Error in service module.
160 PAM_SYSTEM_ERR System error.
163 PAM_BUF_ERR Memory buffer error.
166 PAM_CONV_ERR Conversation failure.
169 PAM_PERM_DENIED Permission denied.
172
175 See attributes(5) for description of the following attributes:
176 ┌─────────────────────────────┬─────────────────────────────┐
181 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
182 ├─────────────────────────────┼─────────────────────────────┤
183 │MT Level │MT-Safe with exceptions │
184 └─────────────────────────────┴─────────────────────────────┘
185
187 login(1), pam_authenticate(3PAM), pam_chauthtok(3PAM), pam_open_ses‐
188 sion(3PAM), pam_set_item(3PAM), pam_setcred(3PAM), pam_sm(3PAM),
189 pam_start(3PAM), pam_strerror(3PAM), pam.conf(4), attributes(5)
190 Solaris Security for Developers Guide
193
195 The interfaces in libpam() are MT-Safe only if each thread within the
196 multithreaded application uses its own PAM handle.
197SunOS 5.11 22 Feb 2005 pam(3PAM)