1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
7 <refentrytitle>pam</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
12 <refnamediv id='pam3-name'>
13 <refname>pam</refname>
14 <refpurpose>Pluggable Authentication Modules Library</refpurpose>
17 <refsynopsisdiv id='pam3-synopsis'>
19 <funcsynopsisinfo>#include <security/pam_appl.h></funcsynopsisinfo>
20 <funcsynopsisinfo>#include <security/pam_modules.h></funcsynopsisinfo>
21 <funcsynopsisinfo>#include <security/pam_ext.h></funcsynopsisinfo>
25 <refsect1 id='pam3-description'>
26 <title>DESCRIPTION</title>
28 <emphasis remap='B'>PAM</emphasis> is a system of libraries
29 that handle the authentication tasks of applications (services)
30 on the system. The library provides a stable general interface
31 (Application Programming Interface - API) that privilege granting
34 <refentrytitle>login</refentrytitle><manvolnum>1</manvolnum>
35 </citerefentry> and <citerefentry>
36 <refentrytitle>su</refentrytitle><manvolnum>1</manvolnum>
38 defer to to perform standard authentication tasks.
41 <refsect2 id='pam3-initialization_and_cleanup'>
42 <title>Initialization and Cleanup</title>
46 <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
47 </citerefentry> function creates the PAM context and initiates the
48 PAM transaction. It is the first of the PAM functions that needs to
49 be called by an application. The transaction state is contained
50 entirely within the structure identified by this handle, so it is
51 possible to have multiple transactions in parallel. But it is not
52 possible to use the same handle for different transactions, a new
53 one is needed for every new context.
58 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
59 </citerefentry> function terminates the PAM transaction and is the last
60 function an application should call in the PAM context. Upon return
61 the handle pamh is no longer valid and all memory associated with it
62 will be invalid. It can be called at any time to terminate a PAM
67 <refsect2 id='pam3-authentication'>
68 <title>Authentication</title>
72 <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
75 authenticate the user. The user is required to provide an
76 authentication token depending upon the authentication service,
77 usually this is a password, but could also be a finger print.
82 <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
84 function manages the userscredentials.
88 <refsect2 id='pam3-account_management'>
89 <title>Account Management</title>
93 <refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
94 </citerefentry> function is used to determine if the users account is
95 valid. It checks for authentication token and account expiration and
96 verifies access restrictions. It is typically called after the user
97 has been authenticated.
101 <refsect2 id='pam3-password_management'>
102 <title>Password Management</title>
106 <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
107 </citerefentry> function is used to change the authentication token
108 for a given user on request or because the token has expired.
112 <refsect2 id='pam3-session_management'>
113 <title>Session Management</title>
117 <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
118 </citerefentry> function sets up a user session for a previously
119 successful authenticated user. The session should later be terminated
122 <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
127 <refsect2 id='pam3-conversation'>
128 <title>Conversation</title>
130 The PAM library uses an application-defined callback to allow
131 a direct communication between a loaded module and the application.
132 This callback is specified by the
133 <emphasis>struct pam_conv</emphasis> passed to
135 <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
136 </citerefentry> at the start of the transaction. See
138 <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
144 <refsect2 id='pam3-data'>
145 <title>Data Objects</title>
149 <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
153 <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
155 functions allows applications and PAM service modules to set and
156 retrieve PAM informations.
161 <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
163 function is the preferred method to obtain the username.
168 <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
172 <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
174 functions allows PAM service modules to set and retrieve free-form
175 data from one invocation to another.
179 <refsect2 id='pam3-miscellaneous'>
180 <title>Environment and Error Management</title>
184 <refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
187 <refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
190 <refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
192 functions are for maintaining a set of private environment variables.
198 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
199 </citerefentry> function returns a pointer to a string describing the
200 given PAM error code.
205 <refsect1 id='pam3-return_values'>
206 <title>RETURN VALUES</title>
208 The following return codes are known by PAM:
212 <term>PAM_ABORT</term>
214 <para>Critical error, immediate abort.</para>
218 <term>PAM_ACCT_EXPIRED</term>
220 <para>User account has expired.</para>
224 <term>PAM_AUTHINFO_UNAVAIL</term>
227 Authentication service cannot retrieve authentication info.
232 <term>PAM_AUTHTOK_DISABLE_AGING</term>
234 <para>Authentication token aging disabled.</para>
238 <term>PAM_AUTHTOK_ERR</term>
240 <para>Authentication token manipulation error.</para>
244 <term>PAM_AUTHTOK_EXPIRED</term>
246 <para>Authentication token expired.</para>
250 <term>PAM_AUTHTOK_LOCK_BUSY</term>
252 <para>Authentication token lock busy.</para>
256 <term>PAM_AUTHTOK_RECOVERY_ERR</term>
258 <para>Authentication information cannot be recovered.</para>
262 <term>PAM_AUTH_ERR</term>
264 <para>Authentication failure.</para>
268 <term>PAM_BUF_ERR</term>
270 <para>Memory buffer error.</para>
274 <term>PAM_CONV_ERR</term>
276 <para>Conversation failure.</para>
280 <term>PAM_CRED_ERR</term>
282 <para>Failure setting user credentials.</para>
286 <term>PAM_CRED_EXPIRED</term>
288 <para>User credentials expired.</para>
292 <term>PAM_CRED_INSUFFICIENT</term>
294 <para>Insufficient credentials to access authentication data.</para>
298 <term>PAM_CRED_UNAVAIL</term>
300 <para>Authentication service cannot retrieve user credentials.</para>
304 <term>PAM_IGNORE</term>
306 <para>The return value should be ignored by PAM dispatch.</para>
310 <term>PAM_MAXTRIES</term>
312 <para>Have exhausted maximum number of retries for service.</para>
316 <term>PAM_MODULE_UNKNOWN</term>
318 <para>Module is unknown.</para>
322 <term>PAM_NEW_AUTHTOK_REQD</term>
325 Authentication token is no longer valid; new one required.
330 <term>PAM_NO_MODULE_DATA</term>
332 <para>No module specific data is present.</para>
336 <term>PAM_OPEN_ERR</term>
338 <para>Failed to load module.</para>
342 <term>PAM_PERM_DENIED</term>
344 <para>Permission denied.</para>
348 <term>PAM_SERVICE_ERR</term>
350 <para>Error in service module.</para>
354 <term>PAM_SESSION_ERR</term>
356 <para>Cannot make/remove an entry for the specified session.</para>
360 <term>PAM_SUCCESS</term>
362 <para>Success.</para>
366 <term>PAM_SYMBOL_ERR</term>
368 <para>Symbol not found.</para>
372 <term>PAM_SYSTEM_ERR</term>
374 <para>System error.</para>
378 <term>PAM_TRY_AGAIN</term>
380 <para>Failed preliminary check by password service.</para>
384 <term>PAM_USER_UNKNOWN</term>
386 <para>User not known to the underlying authentication module.</para>
392 <refsect1 id='see_also'><title>SEE ALSO</title>
395 <refentrytitle>pam_acct_mgmt</refentrytitle><manvolnum>3</manvolnum>
396 </citerefentry>, <citerefentry>
397 <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
398 </citerefentry>, <citerefentry>
399 <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
400 </citerefentry>, <citerefentry>
401 <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
402 </citerefentry>, <citerefentry>
403 <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
404 </citerefentry>, <citerefentry>
405 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
406 </citerefentry>, <citerefentry>
407 <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
408 </citerefentry>, <citerefentry>
409 <refentrytitle>pam_getenv</refentrytitle><manvolnum>3</manvolnum>
410 </citerefentry>, <citerefentry>
411 <refentrytitle>pam_getenvlist</refentrytitle><manvolnum>3</manvolnum>
412 </citerefentry>, <citerefentry>
413 <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
414 </citerefentry>, <citerefentry>
415 <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
416 </citerefentry>, <citerefentry>
417 <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
418 </citerefentry>, <citerefentry>
419 <refentrytitle>pam_putenv</refentrytitle><manvolnum>3</manvolnum>
420 </citerefentry>, <citerefentry>
421 <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
422 </citerefentry>, <citerefentry>
423 <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
424 </citerefentry>, <citerefentry>
425 <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
426 </citerefentry>, <citerefentry>
427 <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
428 </citerefentry>, <citerefentry>
429 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>