2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
3 .\" All rights reserved.
5 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
6 .\" Network Associates Laboratories, the Security Research Division of
7 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
8 .\" ("CBOSS"), as part of the DARPA CHATS research program.
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\" notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in the
17 .\" documentation and/or other materials provided with the distribution.
18 .\" 3. The name of the author may not be used to endorse or promote
19 .\" products derived from this software without specific prior written
22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
41 .Nm pam_authenticate ,
43 .Nm pam_close_session ,
50 .Nm pam_open_session ,
57 .Nd Pluggable Authentication Modules Library
61 .In security/pam_appl.h
63 .Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
65 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
67 .Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
69 .Fn pam_close_session "pam_handle_t *pamh" "int flags"
71 .Fn pam_end "pam_handle_t *pamh" "int status"
73 .Fn pam_get_data "pam_handle_t *pamh" "const char *module_data_name" "void **data"
75 .Fn pam_get_item "pam_handle_t *pamh" "int item_type" "const void **item"
77 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
79 .Fn pam_getenv "pam_handle_t *pamh" "const char *name"
81 .Fn pam_getenvlist "pam_handle_t *pamh"
83 .Fn pam_open_session "pam_handle_t *pamh" "int flags"
85 .Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue"
87 .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)"
89 .Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item"
91 .Fn pam_setcred "pam_handle_t *pamh" "int flags"
93 .Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh"
95 .Fn pam_strerror "pam_handle_t *pamh" "int error_number"
97 .\" $P4: //depot/projects/openpam/doc/man/pam.man#4 $
100 The Pluggable Authentication Modules (PAM) library abstracts a number
101 of common authentication-related operations and provides a framework
102 for dynamically loaded modules that implement these operations in
105 In PAM parlance, the application that uses PAM to authenticate a user
106 is the server, and is identified for configuration purposes by a
107 service name, which is often (but not necessarily) the program name.
109 The user requesting authentication is called the applicant, while the
110 user (usually, root) charged with verifying his identity and granting
111 him the requested credentials is called the arbitrator.
113 The sequence of operations the server goes through to authenticate a
114 user and perform whatever task he requested is a PAM transaction; the
115 context within which the server performs the requested task is called
118 The functionality embodied by PAM is divided into six primitives
119 grouped into four facilities: authentication, account management,
120 session management and password management.
122 The PAM library expects the application to provide a conversation
123 callback which it can use to communicate with the user.
124 Some modules may use specialized conversation functions to communicate
125 with special hardware such as cryptographic dongles or biometric
130 .Ss Initialization and Cleanup
133 function initializes the PAM library and returns a handle which must
134 be provided in all subsequent function calls.
135 The transaction state is contained entirely within the structure
136 identified by this handle, so it is possible to conduct multiple
137 transactions in parallel.
141 function releases all resources associated with the specified context,
142 and can be called at any time to terminate a PAM transaction.
148 functions set and retrieve a number of predefined items, including the
149 service name, the names of the requesting and target users, the
150 conversation function, and prompts.
156 functions manage named chunks of free-form data, generally used by
157 modules to store state from one invocation to another.
159 There are two authentication primitives:
163 The former authenticates the user, while the latter manages his
165 .Ss Account Management
168 function enforces policies such as password expiry, account expiry,
169 time-of-day restrictions, and so forth.
170 .Ss Session Management
174 .Fn pam_close_session
175 functions handle session setup and teardown.
176 .Ss Password Management
179 function allows the server to change the user's password, either at
180 the user's request or because the password has expired.
187 functions manage a private environment list in which modules can set
188 environment variables they want the server to export during the
193 function returns a pointer to a string describing the specified PAM
196 The following return codes are defined by
197 .In security/pam_constants.h :
201 .It Bq Er PAM_ACCT_EXPIRED
202 User account has expired.
203 .It Bq Er PAM_AUTHINFO_UNAVAIL
204 Authentication information is unavailable.
205 .It Bq Er PAM_AUTHTOK_DISABLE_AGING
206 Authentication token aging disabled.
207 .It Bq Er PAM_AUTHTOK_ERR
208 Authentication token failure.
209 .It Bq Er PAM_AUTHTOK_EXPIRED
210 Password has expired.
211 .It Bq Er PAM_AUTHTOK_LOCK_BUSY
212 Authentication token lock busy.
213 .It Bq Er PAM_AUTHTOK_RECOVERY_ERR
214 Failed to recover old authentication token.
215 .It Bq Er PAM_AUTH_ERR
216 Authentication error.
217 .It Bq Er PAM_BUF_ERR
219 .It Bq Er PAM_CONV_ERR
220 Conversation failure.
221 .It Bq Er PAM_CRED_ERR
222 Failed to set user credentials.
223 .It Bq Er PAM_CRED_EXPIRED
224 User credentials have expired.
225 .It Bq Er PAM_CRED_INSUFFICIENT
226 Insufficient credentials.
227 .It Bq Er PAM_CRED_UNAVAIL
228 Failed to retrieve user credentials.
229 .It Bq Er PAM_DOMAIN_UNKNOWN
230 Unknown authentication domain.
233 .It Bq Er PAM_MAXTRIES
234 Maximum number of tries exceeded.
235 .It Bq Er PAM_MODULE_UNKNOWN
237 .It Bq Er PAM_NEW_AUTHTOK_REQD
238 New authentication token required.
239 .It Bq Er PAM_NO_MODULE_DATA
240 Module data not found.
241 .It Bq Er PAM_OPEN_ERR
242 Failed to load module.
243 .It Bq Er PAM_PERM_DENIED
245 .It Bq Er PAM_SERVICE_ERR
246 Error in service module.
247 .It Bq Er PAM_SESSION_ERR
249 .It Bq Er PAM_SUCCESS
251 .It Bq Er PAM_SYMBOL_ERR
253 .It Bq Er PAM_SYSTEM_ERR
255 .It Bq Er PAM_TRY_AGAIN
257 .It Bq Er PAM_USER_UNKNOWN
262 .Xr pam_acct_mgmt 3 ,
263 .Xr pam_authenticate 3 ,
264 .Xr pam_chauthtok 3 ,
265 .Xr pam_close_session 3 ,
270 .Xr pam_getenvlist 3 ,
273 .Xr pam_open_session 3 ,
282 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
286 The OpenPAM library and this manual page were developed for the
288 Project by ThinkSec AS and Network Associates Laboratories, the
289 Security Research Division of Network Associates, Inc.\& under
290 DARPA/SPAWAR contract N66001-01-C-8035
292 as part of the DARPA CHATS research program.