1 .\" Generated by gendoc.pl
6 .Nd Pluggable Authentication Modules Library
10 .In security/pam_appl.h
12 .\" $Id: pam.man 648 2013-03-05 17:54:27Z des $
15 The Pluggable Authentication Modules (PAM) library abstracts a number
16 of common authentication-related operations and provides a framework
17 for dynamically loaded modules that implement these operations in
20 In PAM parlance, the application that uses PAM to authenticate a user
21 is the server, and is identified for configuration purposes by a
22 service name, which is often (but not necessarily) the program name.
24 The user requesting authentication is called the applicant, while the
25 user (usually, root) charged with verifying his identity and granting
26 him the requested credentials is called the arbitrator.
28 The sequence of operations the server goes through to authenticate a
29 user and perform whatever task he requested is a PAM transaction; the
30 context within which the server performs the requested task is called
33 The functionality embodied by PAM is divided into six primitives
34 grouped into four facilities: authentication, account management,
35 session management and password management.
37 The PAM library expects the application to provide a conversation
38 callback which it can use to communicate with the user.
39 Some modules may use specialized conversation functions to communicate
40 with special hardware such as cryptographic dongles or biometric
45 .Ss Initialization and Cleanup
48 function initializes the PAM library and returns a handle which must
49 be provided in all subsequent function calls.
50 The transaction state is contained entirely within the structure
51 identified by this handle, so it is possible to conduct multiple
52 transactions in parallel.
56 function releases all resources associated with the specified context,
57 and can be called at any time to terminate a PAM transaction.
63 functions set and retrieve a number of predefined items, including the
64 service name, the names of the requesting and target users, the
65 conversation function, and prompts.
71 functions manage named chunks of free-form data, generally used by
72 modules to store state from one invocation to another.
74 There are two authentication primitives:
78 The former authenticates the user, while the latter manages his
80 .Ss Account Management
83 function enforces policies such as password expiry, account expiry,
84 time-of-day restrictions, and so forth.
85 .Ss Session Management
90 functions handle session setup and teardown.
91 .Ss Password Management
94 function allows the server to change the user's password, either at
95 the user's request or because the password has expired.
102 functions manage a private environment list in which modules can set
103 environment variables they want the server to export during the
108 function returns a pointer to a string describing the specified PAM
111 The following return codes are defined by
112 .In security/pam_constants.h :
116 .It Bq Er PAM_ACCT_EXPIRED
117 User account has expired.
118 .It Bq Er PAM_AUTHINFO_UNAVAIL
119 Authentication information is unavailable.
120 .It Bq Er PAM_AUTHTOK_DISABLE_AGING
121 Authentication token aging disabled.
122 .It Bq Er PAM_AUTHTOK_ERR
123 Authentication token failure.
124 .It Bq Er PAM_AUTHTOK_EXPIRED
125 Password has expired.
126 .It Bq Er PAM_AUTHTOK_LOCK_BUSY
127 Authentication token lock busy.
128 .It Bq Er PAM_AUTHTOK_RECOVERY_ERR
129 Failed to recover old authentication token.
130 .It Bq Er PAM_AUTH_ERR
131 Authentication error.
132 .It Bq Er PAM_BUF_ERR
134 .It Bq Er PAM_CONV_ERR
135 Conversation failure.
136 .It Bq Er PAM_CRED_ERR
137 Failed to set user credentials.
138 .It Bq Er PAM_CRED_EXPIRED
139 User credentials have expired.
140 .It Bq Er PAM_CRED_INSUFFICIENT
141 Insufficient credentials.
142 .It Bq Er PAM_CRED_UNAVAIL
143 Failed to retrieve user credentials.
144 .It Bq Er PAM_DOMAIN_UNKNOWN
145 Unknown authentication domain.
148 .It Bq Er PAM_MAXTRIES
149 Maximum number of tries exceeded.
150 .It Bq Er PAM_MODULE_UNKNOWN
152 .It Bq Er PAM_NEW_AUTHTOK_REQD
153 New authentication token required.
154 .It Bq Er PAM_NO_MODULE_DATA
155 Module data not found.
156 .It Bq Er PAM_OPEN_ERR
157 Failed to load module.
158 .It Bq Er PAM_PERM_DENIED
160 .It Bq Er PAM_SERVICE_ERR
161 Error in service module.
162 .It Bq Er PAM_SESSION_ERR
164 .It Bq Er PAM_SUCCESS
166 .It Bq Er PAM_SYMBOL_ERR
168 .It Bq Er PAM_SYSTEM_ERR
170 .It Bq Er PAM_TRY_AGAIN
172 .It Bq Er PAM_USER_UNKNOWN
180 .%T "X/Open Single Sign-On Service (XSSO) - Pluggable Authentication Modules"
184 The OpenPAM library and this manual page were developed for the
186 Project by ThinkSec AS and Network Associates Laboratories, the
187 Security Research Division of Network Associates, Inc.\& under
188 DARPA/SPAWAR contract N66001-01-C-8035
190 as part of the DARPA CHATS research program.
192 The OpenPAM library is maintained by
193 .An Dag-Erling Sm\(/orgrav Aq des@des.no .