pam_sm(3pam)

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

NAME

6       pam_sm - PAM Service Module APIs
7

SYNOPSIS

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

DESCRIPTION

15       PAM gives system administrators the flexibility of choosing any authen‐
16       tication service available on the system to perform authentication. The
17       framework  also allows new authentication service modules to be plugged
18       in and made available without modifying the applications.
19
20
21       The PAM framework, libpam, consists of an interface library and  multi‐
22       ple  authentication   service modules. The PAM interface library is the
23       layer that implements the Application Programming Interface  (  API  ).
24       The  authentication  service  modules are a set of dynamically loadable
25       objects invoked by the PAM API to provide a  particular  type  of  user
26       authentication.
27
28
29       This manual page gives an overview of the PAM APIs for the service mod‐
30       ules, also called the Service Provider Interface (PAM-SPI).
31
32   Interface Overview
33       The PAM service module interface consists of  functions  which  can  be
34       grouped  into  four  categories.  The  names for all the authentication
35       library functions start with pam_sm. The only  difference  between  the
36       pam_*()  interfaces  and  their  corresponding pam_sm_*() interfaces is
37       that all the pam_sm_*() interfaces require  extra  parameters  to  pass
38       service-specific  options  to  the  shared  modules. They are otherwise
39       identical.
40
41
42       The first category contains functions  to  authenticate  an  individual
43       user,  pam_sm_authenticate(3PAM),  and  to  set  the credentials of the
44       user, pam_sm_setcred(3PAM).  These  back-end  functions  implement  the
45       functionality  of  pam_authenticate(3PAM) and pam_setcred(3PAM) respec‐
46       tively.
47
48
49       The second category contains the function  to  do  account  management:
50       pam_sm_acct_mgmt(3PAM).  This  includes checking for password aging and
51       access-hour restrictions. This back-end function implements  the  func‐
52       tionality of pam_acct_mgmt(3PAM).
53
54
55       The third category contains the functions pam_sm_open_session(3PAM) and
56       pam_sm_close_session(3PAM) to perform session management  after  access
57       to  the system has been granted. These back-end functions implement the
58       functionality of  pam_open_session(3PAM)  and  pam_close_session(3PAM),
59       respectively.
60
61
62       The fourth category consists a function to change authentication tokens
63       pam_sm_chauthtok(3PAM). This back-end function implements the function‐
64       ality of pam_chauthtok(3PAM).
65
66   Stateful Interface
67       A  sequence  of  calls  sharing  a  common  set of state information is
68       referred to as an authentication transaction. An authentication  trans‐
69       action  begins with a call to pam_start(). pam_start() allocates space,
70       performs various initialization activities, and assigns an  authentica‐
71       tion  handle  to be used for subsequent calls to the library. Note that
72       the service modules do not get called or initialized  when  pam_start()
73       is  called.  The modules are loaded and the symbols resolved upon first
74       use of that function.
75
76
77       The PAM handle keeps certain information about the transaction that can
78       be accessed through the pam_get_item() API. Though the modules can also
79       use pam_set_item() to change any of the item information, it is  recom‐
80       mended that nothing be changed except PAM_AUTHTOK and PAM_OLDAUTHTOK.
81
82
83       If the modules want to store any module specific state information then
84       they can use the pam_set_data(3PAM) function to store that  information
85       with  the  PAM  handle.  The data should be stored with a name which is
86       unique  across   all   modules   and   module   types.   For   example,
87       SUNW_PAM_UNIX_AUTH_userid  can  be used as a name by the UNIX module to
88       store information about the state of user's authentication.  Some  mod‐
89       ules  use  this  technique  to  share  data across two different module
90       types.
91
92
93       Also, during the call to pam_authenticate(), the UNIX module may  store
94       the  authentication  status (success or reason for failure) in the han‐
95       dle, using a unique name such as SUNW_SECURE_RPC_DATA. This information
96       is intended for use by pam_setcred().
97
98
99       During  the call to pam_acct_mgmt(), the account modules may store data
100       in the handle to indicate which passwords have aged.  This  information
101       is intended for use by pam_chauthtok().
102
103
104       The  module can also store a cleanup function associated with the data.
105       The PAM framework calls this cleanup  function,  when  the  application
106       calls pam_end() to close the transaction.
107
108   Interaction with the User
109       The  PAM  service  modules  do  not communicate directly with the user;
110       instead they rely on the application to perform all such  interactions.
111       The  application  passes  a pointer to the function, conv(), along with
112       any associated application data pointers, through the  pam_conv  struc‐
113       ture  when  it  initiates  an authentication transaction (by means of a
114       call to pam_start(). The service module will  then  use  the  function,
115       conv(), to prompt the user for data, output error messages, and display
116       text information. Refer to pam_start(3PAM) for  more  information.  The
117       modules  are  responsible  for  the localization of all messages to the
118       user.
119
120   Conventions
121       By convention, applications that need to prompt for a user name  should
122       call pam_set_item() and set the value of PAM_USER_PROMPT before calling
123       pam_authenticate(). The service module's pam_sm_authenticate() function
124       will  then  call  pam_get_user() to prompt for the user name. Note that
125       certain PAM service modules (such as a smart card module) may  override
126       the value of PAM_USER_PROMPT and pass in their own prompt.
127
128
129       Though  the  PAM  framework enforces no rules about the module's names,
130       location, options and such, there are certain conventions that all mod‐
131       ule providers are expected to follow.
132
133
134       By  convention,  the modules should be located in the /usr/lib/security
135       directory. Additional modules may be located in /opt/<pkg>/lib.  Archi‐
136       tecture  specific libraries (for example, sparcv9 or amd64) are located
137       in their respective subdirectories.
138
139
140       For every such module, there should be a corresponding manual  page  in
141       section  5 which should describe the module_type it supports, the func‐
142       tionality of the module, along with the options it supports. The depen‐
143       dencies  should  be clearly identified to the system administrator. For
144       example, it should be made clear whether this module is  a  stand-alone
145       module  or  depends  upon the presence of some other module. One should
146       also specify whether this module should come before or after some other
147       module in the stack.
148
149
150       By convention, the modules should support the following options:
151
152       debug     Syslog  debugging  information at LOG_DEBUG level. Be careful
153                 as to not log any sensitive information such as passwords.
154
155
156       nowarn    Turn off warning messages  such  as  "password  is  about  to
157                 expire."
158
159
160
161       If an unsupported option is passed to the modules, it should syslog the
162       error at LOG_ERR level.
163
164
165       The permission bits on the service module should be set such that it is
166       not  writable  by  either "group" or "other." The service module should
167       also be owned by root. The PAM framework will not load  the  module  if
168       the above permission rules are not followed.
169

ERRORS

171       If  there  are any errors, the modules should log them using syslog(3C)
172       at the LOG_ERR level.
173

RETURN VALUES

175       The PAM service module functions may return any of the PAM  error  num‐
176       bers  specified  in  the  specific  man  pages.  It  can  also return a
177       PAM_IGNORE error number to mean that the PAM  framework  should  ignore
178       this  module  regardless  of whether it is required, optional or suffi‐
179       cient. This error number is normally returned when the module does  not
180       contribute to the decision being made by the PAM framework.
181

ATTRIBUTES

183       See attributes(5) for description of the following attributes:
184
185
186
187
188       ┌─────────────────────────────┬─────────────────────────────┐
189       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
190       ├─────────────────────────────┼─────────────────────────────┤
191       │Interface Stability          │ Stable                      │
192       ├─────────────────────────────┼─────────────────────────────┤
193       │MT-Level                     │MT-Safe with exceptions      │
194       └─────────────────────────────┴─────────────────────────────┘
195

NOTES

207       The interfaces in libpam are MT-Safe only if  each  thread  within  the
208       multithreaded application uses its own PAM handle.
209
210
211
212SunOS 5.11                        16 Mar 2005                     pam_sm(3PAM)