1 .\" Generated by gendoc.pl
9 .Nm pam_close_session ,
16 .Nm pam_open_session ,
23 .Nd Pluggable Authentication Modules Library
27 .In security/pam_appl.h
29 .Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
31 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
33 .Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
35 .Fn pam_close_session "pam_handle_t *pamh" "int flags"
37 .Fn pam_end "pam_handle_t *pamh" "int status"
39 .Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data"
41 .Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item"
43 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
45 .Fn pam_getenv "pam_handle_t *pamh" "const char *name"
47 .Fn pam_getenvlist "pam_handle_t *pamh"
49 .Fn pam_open_session "pam_handle_t *pamh" "int flags"
51 .Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue"
53 .Fn pam_set_data "pam_handle_t *pamh" "const char *module_data_name" "void *data" "void (*cleanup)(pam_handle_t *pamh, void *data, int pam_end_status)"
55 .Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item"
57 .Fn pam_setcred "pam_handle_t *pamh" "int flags"
59 .Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh"
61 .Fn pam_strerror "const pam_handle_t *pamh" "int error_number"
63 .\" $OpenPAM: pam.man 938 2017-04-30 21:34:42Z des $
66 The Pluggable Authentication Modules (PAM) library abstracts a number
67 of common authentication-related operations and provides a framework
68 for dynamically loaded modules that implement these operations in
71 In PAM parlance, the application that uses PAM to authenticate a user
72 is the server, and is identified for configuration purposes by a
73 service name, which is often (but not necessarily) the program name.
75 The user requesting authentication is called the applicant, while the
76 user (usually, root) charged with verifying his identity and granting
77 him the requested credentials is called the arbitrator.
79 The sequence of operations the server goes through to authenticate a
80 user and perform whatever task he requested is a PAM transaction; the
81 context within which the server performs the requested task is called
84 The functionality embodied by PAM is divided into six primitives
85 grouped into four facilities: authentication, account management,
86 session management and password management.
88 The PAM library expects the application to provide a conversation
89 callback which it can use to communicate with the user.
90 Some modules may use specialized conversation functions to communicate
91 with special hardware such as cryptographic dongles or biometric
96 .Ss Initialization and Cleanup
99 function initializes the PAM library and returns a handle which must
100 be provided in all subsequent function calls.
101 The transaction state is contained entirely within the structure
102 identified by this handle, so it is possible to conduct multiple
103 transactions in parallel.
107 function releases all resources associated with the specified context,
108 and can be called at any time to terminate a PAM transaction.
114 functions set and retrieve a number of predefined items, including the
115 service name, the names of the requesting and target users, the
116 conversation function, and prompts.
122 functions manage named chunks of free-form data, generally used by
123 modules to store state from one invocation to another.
125 There are two authentication primitives:
129 The former authenticates the user, while the latter manages his
131 .Ss Account Management
134 function enforces policies such as password expiry, account expiry,
135 time-of-day restrictions, and so forth.
136 .Ss Session Management
140 .Fn pam_close_session
141 functions handle session setup and teardown.
142 .Ss Password Management
145 function allows the server to change the user's password, either at
146 the user's request or because the password has expired.
153 functions manage a private environment list in which modules can set
154 environment variables they want the server to export during the
159 function returns a pointer to a string describing the specified PAM
162 The following return codes are defined by
163 .In security/pam_constants.h :
167 .It Bq Er PAM_ACCT_EXPIRED
168 User account has expired.
169 .It Bq Er PAM_AUTHINFO_UNAVAIL
170 Authentication information is unavailable.
171 .It Bq Er PAM_AUTHTOK_DISABLE_AGING
172 Authentication token aging disabled.
173 .It Bq Er PAM_AUTHTOK_ERR
174 Authentication token failure.
175 .It Bq Er PAM_AUTHTOK_EXPIRED
176 Password has expired.
177 .It Bq Er PAM_AUTHTOK_LOCK_BUSY
178 Authentication token lock busy.
179 .It Bq Er PAM_AUTHTOK_RECOVERY_ERR
180 Failed to recover old authentication token.
181 .It Bq Er PAM_AUTH_ERR
182 Authentication error.
183 .It Bq Er PAM_BAD_CONSTANT
185 .It Bq Er PAM_BAD_FEATURE
186 Unrecognized or restricted feature.
187 .It Bq Er PAM_BAD_HANDLE
189 .It Bq Er PAM_BAD_ITEM
190 Unrecognized or restricted item.
191 .It Bq Er PAM_BUF_ERR
193 .It Bq Er PAM_CONV_ERR
194 Conversation failure.
195 .It Bq Er PAM_CRED_ERR
196 Failed to set user credentials.
197 .It Bq Er PAM_CRED_EXPIRED
198 User credentials have expired.
199 .It Bq Er PAM_CRED_INSUFFICIENT
200 Insufficient credentials.
201 .It Bq Er PAM_CRED_UNAVAIL
202 Failed to retrieve user credentials.
203 .It Bq Er PAM_DOMAIN_UNKNOWN
204 Unknown authentication domain.
207 .It Bq Er PAM_MAXTRIES
208 Maximum number of tries exceeded.
209 .It Bq Er PAM_MODULE_UNKNOWN
211 .It Bq Er PAM_NEW_AUTHTOK_REQD
212 New authentication token required.
213 .It Bq Er PAM_NO_MODULE_DATA
214 Module data not found.
215 .It Bq Er PAM_OPEN_ERR
216 Failed to load module.
217 .It Bq Er PAM_PERM_DENIED
219 .It Bq Er PAM_SERVICE_ERR
220 Error in service module.
221 .It Bq Er PAM_SESSION_ERR
223 .It Bq Er PAM_SUCCESS
225 .It Bq Er PAM_SYMBOL_ERR
227 .It Bq Er PAM_SYSTEM_ERR
229 .It Bq Er PAM_TRY_AGAIN
231 .It Bq Er PAM_USER_UNKNOWN
236 .Xr pam_acct_mgmt 3 ,
237 .Xr pam_authenticate 3 ,
238 .Xr pam_chauthtok 3 ,
239 .Xr pam_close_session 3 ,
244 .Xr pam_getenvlist 3 ,
247 .Xr pam_open_session 3 ,
256 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
260 The OpenPAM library and this manual page were developed for the
262 Project by ThinkSec AS and Network Associates Laboratories, the
263 Security Research Division of Network Associates, Inc.\& under
264 DARPA/SPAWAR contract N66001-01-C-8035
266 as part of the DARPA CHATS research program.
268 The OpenPAM library is maintained by
269 .An Dag-Erling Sm\(/orgrav Aq Mt des@des.no .