2 .\" Copyright (c) 2001-2003 Networks Associates Technology, Inc.
3 .\" Copyright (c) 2004-2007 Dag-Erling Smørgrav
4 .\" All rights reserved.
6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
7 .\" Network Associates Laboratories, the Security Research Division of
8 .\" Network Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035
9 .\" ("CBOSS"), as part of the DARPA CHATS research program.
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\" notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\" notice, this list of conditions and the following disclaimer in the
18 .\" documentation and/or other materials provided with the distribution.
19 .\" 3. The name of the author may not be used to endorse or promote
20 .\" products derived from this software without specific prior written
23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
42 .Nm pam_authenticate ,
44 .Nm pam_close_session ,
51 .Nm pam_open_session ,
58 .Nd Pluggable Authentication Modules Library
62 .In security/pam_appl.h
64 .Fn pam_acct_mgmt "pam_handle_t *pamh" "int flags"
66 .Fn pam_authenticate "pam_handle_t *pamh" "int flags"
68 .Fn pam_chauthtok "pam_handle_t *pamh" "int flags"
70 .Fn pam_close_session "pam_handle_t *pamh" "int flags"
72 .Fn pam_end "pam_handle_t *pamh" "int status"
74 .Fn pam_get_data "const pam_handle_t *pamh" "const char *module_data_name" "const void **data"
76 .Fn pam_get_item "const pam_handle_t *pamh" "int item_type" "const void **item"
78 .Fn pam_get_user "pam_handle_t *pamh" "const char **user" "const char *prompt"
80 .Fn pam_getenv "pam_handle_t *pamh" "const char *name"
82 .Fn pam_getenvlist "pam_handle_t *pamh"
84 .Fn pam_open_session "pam_handle_t *pamh" "int flags"
86 .Fn pam_putenv "pam_handle_t *pamh" "const char *namevalue"
88 .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)"
90 .Fn pam_set_item "pam_handle_t *pamh" "int item_type" "const void *item"
92 .Fn pam_setcred "pam_handle_t *pamh" "int flags"
94 .Fn pam_start "const char *service" "const char *user" "const struct pam_conv *pam_conv" "pam_handle_t **pamh"
96 .Fn pam_strerror "const pam_handle_t *pamh" "int error_number"
98 .\" $Id: pam.man 320 2006-02-16 20:33:19Z des $
101 The Pluggable Authentication Modules (PAM) library abstracts a number
102 of common authentication-related operations and provides a framework
103 for dynamically loaded modules that implement these operations in
106 In PAM parlance, the application that uses PAM to authenticate a user
107 is the server, and is identified for configuration purposes by a
108 service name, which is often (but not necessarily) the program name.
110 The user requesting authentication is called the applicant, while the
111 user (usually, root) charged with verifying his identity and granting
112 him the requested credentials is called the arbitrator.
114 The sequence of operations the server goes through to authenticate a
115 user and perform whatever task he requested is a PAM transaction; the
116 context within which the server performs the requested task is called
119 The functionality embodied by PAM is divided into six primitives
120 grouped into four facilities: authentication, account management,
121 session management and password management.
123 The PAM library expects the application to provide a conversation
124 callback which it can use to communicate with the user.
125 Some modules may use specialized conversation functions to communicate
126 with special hardware such as cryptographic dongles or biometric
131 .Ss Initialization and Cleanup
134 function initializes the PAM library and returns a handle which must
135 be provided in all subsequent function calls.
136 The transaction state is contained entirely within the structure
137 identified by this handle, so it is possible to conduct multiple
138 transactions in parallel.
142 function releases all resources associated with the specified context,
143 and can be called at any time to terminate a PAM transaction.
149 functions set and retrieve a number of predefined items, including the
150 service name, the names of the requesting and target users, the
151 conversation function, and prompts.
157 functions manage named chunks of free-form data, generally used by
158 modules to store state from one invocation to another.
160 There are two authentication primitives:
164 The former authenticates the user, while the latter manages his
166 .Ss Account Management
169 function enforces policies such as password expiry, account expiry,
170 time-of-day restrictions, and so forth.
171 .Ss Session Management
175 .Fn pam_close_session
176 functions handle session setup and teardown.
177 .Ss Password Management
180 function allows the server to change the user's password, either at
181 the user's request or because the password has expired.
188 functions manage a private environment list in which modules can set
189 environment variables they want the server to export during the
194 function returns a pointer to a string describing the specified PAM
197 The following return codes are defined by
198 .In security/pam_constants.h :
202 .It Bq Er PAM_ACCT_EXPIRED
203 User account has expired.
204 .It Bq Er PAM_AUTHINFO_UNAVAIL
205 Authentication information is unavailable.
206 .It Bq Er PAM_AUTHTOK_DISABLE_AGING
207 Authentication token aging disabled.
208 .It Bq Er PAM_AUTHTOK_ERR
209 Authentication token failure.
210 .It Bq Er PAM_AUTHTOK_EXPIRED
211 Password has expired.
212 .It Bq Er PAM_AUTHTOK_LOCK_BUSY
213 Authentication token lock busy.
214 .It Bq Er PAM_AUTHTOK_RECOVERY_ERR
215 Failed to recover old authentication token.
216 .It Bq Er PAM_AUTH_ERR
217 Authentication error.
218 .It Bq Er PAM_BUF_ERR
220 .It Bq Er PAM_CONV_ERR
221 Conversation failure.
222 .It Bq Er PAM_CRED_ERR
223 Failed to set user credentials.
224 .It Bq Er PAM_CRED_EXPIRED
225 User credentials have expired.
226 .It Bq Er PAM_CRED_INSUFFICIENT
227 Insufficient credentials.
228 .It Bq Er PAM_CRED_UNAVAIL
229 Failed to retrieve user credentials.
230 .It Bq Er PAM_DOMAIN_UNKNOWN
231 Unknown authentication domain.
234 .It Bq Er PAM_MAXTRIES
235 Maximum number of tries exceeded.
236 .It Bq Er PAM_MODULE_UNKNOWN
238 .It Bq Er PAM_NEW_AUTHTOK_REQD
239 New authentication token required.
240 .It Bq Er PAM_NO_MODULE_DATA
241 Module data not found.
242 .It Bq Er PAM_OPEN_ERR
243 Failed to load module.
244 .It Bq Er PAM_PERM_DENIED
246 .It Bq Er PAM_SERVICE_ERR
247 Error in service module.
248 .It Bq Er PAM_SESSION_ERR
250 .It Bq Er PAM_SUCCESS
252 .It Bq Er PAM_SYMBOL_ERR
254 .It Bq Er PAM_SYSTEM_ERR
256 .It Bq Er PAM_TRY_AGAIN
258 .It Bq Er PAM_USER_UNKNOWN
263 .Xr pam_acct_mgmt 3 ,
264 .Xr pam_authenticate 3 ,
265 .Xr pam_chauthtok 3 ,
266 .Xr pam_close_session 3 ,
271 .Xr pam_getenvlist 3 ,
274 .Xr pam_open_session 3 ,
283 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
287 The OpenPAM library and this manual page were developed for the
289 Project by ThinkSec AS and Network Associates Laboratories, the
290 Security Research Division of Network Associates, Inc.\& under
291 DARPA/SPAWAR contract N66001-01-C-8035
293 as part of the DARPA CHATS research program.