1pam(3PAM)                    PAM Library Functions                   pam(3PAM)
2
3
4

NAME

6       pam - PAM (Pluggable Authentication Module)
7

SYNOPSIS

9       #include <security/pam_appl.h>
10       cc [ flag... ] file ... -lpam [ library ... ]
11
12

DESCRIPTION

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
25
26       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
30   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
34
35       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
42
43       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
47
48       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
52
53       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
57
58       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
63
64       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
68
69       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
79   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
86
87       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
92
93       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
103
104       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
108
109       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
113
114       To terminate an  authentication  transaction,  the  application  simply
115       calls  pam_end(),  which frees previously allocated space used to store
116       authentication information.
117
118   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
129   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
139   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

RETURN VALUES

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
149       PAM_SUCCESS        The function returned successfully.
150
151
152       PAM_OPEN_ERR       dlopen()  failed  when dynamically loading a service
153                          module.
154
155
156       PAM_SYMBOL_ERR     Symbol not found.
157
158
159       PAM_SERVICE_ERR    Error in service module.
160
161
162       PAM_SYSTEM_ERR     System error.
163
164
165       PAM_BUF_ERR        Memory buffer error.
166
167
168       PAM_CONV_ERR       Conversation failure.
169
170
171       PAM_PERM_DENIED    Permission denied.
172
173

ATTRIBUTES

175       See attributes(5) for description of the following attributes:
176
177
178
179
180       ┌─────────────────────────────┬─────────────────────────────┐
181       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
182       ├─────────────────────────────┼─────────────────────────────┤
183       │MT Level                     │MT-Safe with exceptions      │
184       └─────────────────────────────┴─────────────────────────────┘
185

SEE ALSO

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
191
192       Solaris Security for Developers Guide
193

NOTES

195       The interfaces in  libpam() are MT-Safe only if each thread within  the
196       multithreaded application uses its own  PAM handle.
197
198
199
200SunOS 5.11                        22 Feb 2005                        pam(3PAM)
Impressum