Debian Codegraph @

upstream/debian-unstable/man3/pam.3

raw
1 '\" t
2 .\" Title: pam
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM" "3" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam \- Pluggable Authentication Modules Library
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_appl\&.h>
37 .fi
38 .ft
39 .sp
40 .ft B
41 .nf
42 #include <security/pam_modules\&.h>
43 .fi
44 .ft
45 .sp
46 .ft B
47 .nf
48 #include <security/pam_ext\&.h>
49 .fi
50 .ft
51 .SH "DESCRIPTION"
52 .PP
53 \fBPAM\fR
54 is a system of libraries that handle the authentication tasks of applications (services) on the system\&. The library provides a stable general interface (Application Programming Interface \- API) that privilege granting programs (such as
55 \fBlogin\fR(1)
56 and
57 \fBsu\fR(1)) defer to to perform standard authentication tasks\&.
58 .SS "Initialization and Cleanup"
59 .PP
60 The
61 \fBpam_start\fR(3)
62 function creates the PAM context and initiates the PAM transaction\&. It is the first of the PAM functions that needs to be called by an application\&. The transaction state is contained entirely within the structure identified by this handle, so it is possible to have multiple transactions in parallel\&. But it is not possible to use the same handle for different transactions, a new one is needed for every new context\&.
63 .PP
64 The
65 \fBpam_end\fR(3)
66 function terminates the PAM transaction and is the last function an application should call in the PAM context\&. Upon return the handle pamh is no longer valid and all memory associated with it will be invalid\&. It can be called at any time to terminate a PAM transaction\&.
67 .SS "Authentication"
68 .PP
69 The
70 \fBpam_authenticate\fR(3)
71 function is used to authenticate the user\&. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print\&.
72 .PP
73 The
74 \fBpam_setcred\fR(3)
75 function manages the user\*(Aqs credentials\&.
76 .SS "Account Management"
77 .PP
78 The
79 \fBpam_acct_mgmt\fR(3)
80 function is used to determine if the user\*(Aqs account is valid\&. It checks for authentication token and account expiration and verifies access restrictions\&. It is typically called after the user has been authenticated\&.
81 .SS "Password Management"
82 .PP
83 The
84 \fBpam_chauthtok\fR(3)
85 function is used to change the authentication token for a given user on request or because the token has expired\&.
86 .SS "Session Management"
87 .PP
88 The
89 \fBpam_open_session\fR(3)
90 function sets up a user session for a previously successful authenticated user\&. The session should later be terminated with a call to
91 \fBpam_close_session\fR(3)\&.
92 .SS "Conversation"
93 .PP
94 The PAM library uses an application\-defined callback to allow a direct communication between a loaded module and the application\&. This callback is specified by the
95 \fIstruct pam_conv\fR
96 passed to
97 \fBpam_start\fR(3)
98 at the start of the transaction\&. See
99 \fBpam_conv\fR(3)
100 for details\&.
101 .SS "Data Objects"
102 .PP
103 The
104 \fBpam_set_item\fR(3)
105 and
106 \fBpam_get_item\fR(3)
107 functions allow applications and PAM service modules to set and retrieve PAM information\&.
108 .PP
109 The
110 \fBpam_get_user\fR(3)
111 function is the preferred method to obtain the username\&.
112 .PP
113 The
114 \fBpam_set_data\fR(3)
115 and
116 \fBpam_get_data\fR(3)
117 function allows PAM service modules to set and retrieve free\-form data from one invocation to another\&.
118 .SS "Environment and Error Management"
119 .PP
120 The
121 \fBpam_putenv\fR(3),
122 \fBpam_getenv\fR(3)
123 and
124 \fBpam_getenvlist\fR(3)
125 functions are for maintaining a set of private environment variables\&.
126 .PP
127 The
128 \fBpam_strerror\fR(3)
129 function returns a pointer to a string describing the given PAM error code\&.
130 .SH "RETURN VALUES"
131 .PP
132 The following return codes are known by PAM:
133 .PP
134 PAM_ABORT
135 .RS 4
136 Critical error, immediate abort\&.
137 .RE
138 .PP
139 PAM_ACCT_EXPIRED
140 .RS 4
141 User account has expired\&.
142 .RE
143 .PP
144 PAM_AUTHINFO_UNAVAIL
145 .RS 4
146 Authentication service cannot retrieve authentication info\&.
147 .RE
148 .PP
149 PAM_AUTHTOK_DISABLE_AGING
150 .RS 4
151 Authentication token aging disabled\&.
152 .RE
153 .PP
154 PAM_AUTHTOK_ERR
155 .RS 4
156 Authentication token manipulation error\&.
157 .RE
158 .PP
159 PAM_AUTHTOK_EXPIRED
160 .RS 4
161 Authentication token expired\&.
162 .RE
163 .PP
164 PAM_AUTHTOK_LOCK_BUSY
165 .RS 4
166 Authentication token lock busy\&.
167 .RE
168 .PP
169 PAM_AUTHTOK_RECOVERY_ERR
170 .RS 4
171 Authentication information cannot be recovered\&.
172 .RE
173 .PP
174 PAM_AUTH_ERR
175 .RS 4
176 Authentication failure\&.
177 .RE
178 .PP
179 PAM_BUF_ERR
180 .RS 4
181 Memory buffer error\&.
182 .RE
183 .PP
184 PAM_CONV_ERR
185 .RS 4
186 Conversation failure\&.
187 .RE
188 .PP
189 PAM_CRED_ERR
190 .RS 4
191 Failure setting user credentials\&.
192 .RE
193 .PP
194 PAM_CRED_EXPIRED
195 .RS 4
196 User credentials expired\&.
197 .RE
198 .PP
199 PAM_CRED_INSUFFICIENT
200 .RS 4
201 Insufficient credentials to access authentication data\&.
202 .RE
203 .PP
204 PAM_CRED_UNAVAIL
205 .RS 4
206 Authentication service cannot retrieve user credentials\&.
207 .RE
208 .PP
209 PAM_IGNORE
210 .RS 4
211 The return value should be ignored by PAM dispatch\&.
212 .RE
213 .PP
214 PAM_MAXTRIES
215 .RS 4
216 Have exhausted maximum number of retries for service\&.
217 .RE
218 .PP
219 PAM_MODULE_UNKNOWN
220 .RS 4
221 Module is unknown\&.
222 .RE
223 .PP
224 PAM_NEW_AUTHTOK_REQD
225 .RS 4
226 Authentication token is no longer valid; new one required\&.
227 .RE
228 .PP
229 PAM_NO_MODULE_DATA
230 .RS 4
231 No module specific data is present\&.
232 .RE
233 .PP
234 PAM_OPEN_ERR
235 .RS 4
236 Failed to load module\&.
237 .RE
238 .PP
239 PAM_PERM_DENIED
240 .RS 4
241 Permission denied\&.
242 .RE
243 .PP
244 PAM_SERVICE_ERR
245 .RS 4
246 Error in service module\&.
247 .RE
248 .PP
249 PAM_SESSION_ERR
250 .RS 4
251 Cannot make/remove an entry for the specified session\&.
252 .RE
253 .PP
254 PAM_SUCCESS
255 .RS 4
256 Success\&.
257 .RE
258 .PP
259 PAM_SYMBOL_ERR
260 .RS 4
261 Symbol not found\&.
262 .RE
263 .PP
264 PAM_SYSTEM_ERR
265 .RS 4
266 System error\&.
267 .RE
268 .PP
269 PAM_TRY_AGAIN
270 .RS 4
271 Failed preliminary check by password service\&.
272 .RE
273 .PP
274 PAM_USER_UNKNOWN
275 .RS 4
276 User not known to the underlying authentication module\&.
277 .RE
278 .SH "SEE ALSO"
279 .PP
280 \fBpam_acct_mgmt\fR(3),
281 \fBpam_authenticate\fR(3),
282 \fBpam_chauthtok\fR(3),
283 \fBpam_close_session\fR(3),
284 \fBpam_conv\fR(3),
285 \fBpam_end\fR(3),
286 \fBpam_get_data\fR(3),
287 \fBpam_getenv\fR(3),
288 \fBpam_getenvlist\fR(3),
289 \fBpam_get_item\fR(3),
290 \fBpam_get_user\fR(3),
291 \fBpam_open_session\fR(3),
292 \fBpam_putenv\fR(3),
293 \fBpam_set_data\fR(3),
294 \fBpam_set_item\fR(3),
295 \fBpam_setcred\fR(3),
296 \fBpam_start\fR(3),
297 \fBpam_strerror\fR(3)
298 .SH "NOTES"
299 .PP
300 The
301 \fIlibpam\fR
302 interfaces are only thread\-safe if each thread within the multithreaded application uses its own PAM handle\&.