| blob | 4537e4a58db83b0787de4430847ee45e2f5dc97d |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PAM_KRB5 5 "Apr 8, 2008"
7 .SH NAME
8 pam_krb5 \- authentication, account, session, and password management PAM
9 modules for Kerberos V5
10 .SH SYNOPSIS
11 .LP
12 .nf
13 /usr/lib/security/pam_krb5.so.1
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The Kerberos V5 service module for \fBPAM\fR provides functionality for all
20 four \fBPAM\fR modules: authentication, account management, session management,
21 and password management. The service module is a shared object that can be
22 dynamically loaded to provide the necessary functionality upon demand. Its path
23 is specified in the \fBPAM\fR configuration file.
24 .SS "Kerberos Authentication Module"
25 .sp
26 .LP
27 The Kerberos V5 authentication component provides functions to verify the
28 identity of a user, \fBpam_sm_authenticate()\fR, and to manage the Kerberos
29 credentials cache, \fBpam_sm_setcred()\fR.
30 .sp
31 .LP
32 \fBpam_sm_authenticate()\fR authenticates a user principal through the Kerberos
33 authentication service. If the authentication request is successful, the
34 authentication service sends a ticket-granting ticket (\fBTGT\fR) back to the
35 service module, which then verifies that the \fBTGT\fR came from a valid Key
36 Distribution Center (\fBKDC\fR) by attempting to get a service ticket for the
37 local host service. For this to succeed, the local host's keytab file
38 (\fB/etc/krb5/krb5.keytab\fR) must contain the entry for the local host
39 service. For example, in the file \fBhost/\fIhostname.com\fR@\fIREALM\fR\fR,
40 \fIhostname.com\fR is the fully qualified local hostname and \fIREALM\fR is the
41 default realm of the local host as defined in \fB/etc/krb5/krb5.conf\fR. If the
42 host entry is not found in the keytab file, the authentication fails.
43 Administrators may optionally disable this "strict" verification by setting
44 "\fBverify_ap_req_nofail = false\fR" in \fB/etc/krb5/krb5.conf\fR. See
45 \fBkrb5.conf\fR(4) for more details on this option. This allows \fBTGT\fR
46 verification to succeed in the absence of a keytab host principal entry.
47 .sp
48 .LP
49 \fBpam_sm_authenticate\fR(3PAM) may be passed the following flag:
50 .sp
51 .ne 2
52 .na
53 \fB\fBPAM_DISALLOW_NULL_AUTHTOK\fR\fR
54 .ad
55 .sp .6
56 .RS 4n
57 This flag is ignored. The Kerberos authentication mechanism will not allow an
58 empty password string by default.
59 .RE
61 .sp
62 .LP
63 \fBpam_sm_setcred()\fR creates and modifies the user's credential cache. This
64 function initializes the user's credential cache, if it does not already exist,
65 and stores the initial credentials for later use by Kerberized network
66 applications. The following flags may be set in the flags field. They are best
67 described by their effect on the user's credential cache.
68 .sp
69 .ne 2
70 .na
71 \fB\fBPAM_ESTABLISH_CRED\fR\fR
72 .ad
73 .sp .6
74 .RS 4n
75 Stores the initial credentials in the user's credential cache so that the user
76 may access Kerberos network services. If a successful authentication pass was
77 made, the new credentials are stored in the credential cache, overwriting any
78 existing credentials that were previously stored. If an unsuccessful
79 authentication pass was made, PAM_CRED_UNAVAIL is returned.
80 .RE
82 .sp
83 .ne 2
84 .na
85 \fB\fBPAM_DELETE_CRED\fR\fR
86 .ad
87 .sp .6
88 .RS 4n
89 This flag has no effect on the credential cache and always returns
90 \fBPAM_SUCCESS\fR. The credential cache is not deleted because there is no
91 accurate method to determine if the credentials are needed by another process.
92 The credential cache may be deleted with the \fBkdestroy\fR(1) command.
93 .RE
95 .sp
96 .ne 2
97 .na
98 \fB\fBPAM_REINITIALIZE_CRED\fR\fR
99 .ad
100 .sp .6
101 .RS 4n
102 Deletes the user's existing credential cache, if it exists, and creates a new
103 credential cache. The new credentials are stored in the new cache and the
104 user's ticket lifetime and renewable life time values are reset.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBPAM_REFRESH_CRED\fR\fR
111 .ad
112 .sp .6
113 .RS 4n
114 Does not require a previous authentication pass, but if a successful one is
115 made, the new credentials are stored in the credential cache. If a previous
116 authentication pass was not made or was unsuccessful, an attempt to renew the
117 existing credentials is made. Note that this function fails if the user's
118 renewable ticket lifetime is expired.
119 .RE
121 .sp
122 .LP
123 The following options can be passed to the Kerberos V5 authentication module:
124 .sp
125 .ne 2
126 .na
127 \fB\fBdebug\fR\fR
128 .ad
129 .RS 10n
130 Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
131 .RE
133 .sp
134 .ne 2
135 .na
136 \fB\fBnowarn\fR\fR
137 .ad
138 .RS 10n
139 Turns off warning messages.
140 .RE
142 .SS "Kerberos V5 Account Management Module"
143 .sp
144 .LP
145 The Kerberos account management component provides a function to perform
146 account management, \fBpam_sm_acct_mgmt()\fR. This function checks to see if
147 the \fBpam_krb5\fR authentication module has noted that the user's password has
148 not expired. The following options may be passed in to the Kerberos V5 account
149 management module:
150 .sp
151 .ne 2
152 .na
153 \fBdebug\fR
154 .ad
155 .RS 10n
156 Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level
157 .RE
159 .sp
160 .ne 2
161 .na
162 \fBnowarn\fR
163 .ad
164 .RS 10n
165 Turns off warning messages. Also, does not query KDC for impending password
166 expiration information used to warn the user.
167 .RE
169 .SS "Kerberos V5 Session Management Module"
170 .sp
171 .LP
172 The Kerberos V5 session management component provides functions to initiate
173 \fBpam_sm_open_session()\fR and terminate \fBpam_sm_close_session()\fR Kerberos
174 sessions. For Kerberos V5, both \fBpam_sm_open_session\fR and
175 \fBpam_sm_close_session()\fR are null functions, returning \fBPAM_IGNORE\fR.
176 .SS "Kerberos V5 Password Management Module"
177 .sp
178 .LP
179 The Kerberos V5 password management component provides a function to change
180 passwords, \fBpam_sm_chauthtok()\fR, in the Key Distribution Center (\fBKDC\fR)
181 database. The following flags may be passed to \fBpam_sm_chauthtok\fR(3PAM):
182 .sp
183 .ne 2
184 .na
185 \fB\fBPAM_CHANGE_EXPIRED_AUTHTOK\fR\fR
186 .ad
187 .sp .6
188 .RS 4n
189 The password service should only update the user's Kerberos password if it is
190 expired. Otherwise, this function returns \fBPAM_IGNORE\fR. The default
191 behaviour is to always change the user's Kerberos password.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBPAM_PRELIM_CHECK\fR\fR
198 .ad
199 .sp .6
200 .RS 4n
201 This is a null function that always returns \fBPAM_IGNORE\fR.
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBPAM_UPDATE_AUTHTOK\fR\fR
208 .ad
209 .sp .6
210 .RS 4n
211 This flag is necessary to change the user's Kerberos password. If this flag is
212 not set, \fBpam_krb5\fR returns \fBPAM_SYSTEM_ERR\fR.
213 .RE
215 .sp
216 .LP
217 The following option can be passed to the Kerberos V5 password module:
218 .sp
219 .ne 2
220 .na
221 \fB\fBdebug\fR\fR
222 .ad
223 .RS 9n
224 Provides \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
225 .RE
227 .SH ERRORS
228 .sp
229 .LP
230 The following error codes are returned for \fBpam_sm_authenticate()\fR:
231 .sp
232 .ne 2
233 .na
234 \fB\fBPAM_AUTH_ERR\fR\fR
235 .ad
236 .RS 20n
237 Authentication failure
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fBPAM_BUF_ERR\fR\fR
244 .ad
245 .RS 20n
246 Memory buffer error.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fBPAM_IGNORE\fR\fR
253 .ad
254 .RS 20n
255 The user is "\fBroot\fR" and the root key exists in the default keytab.
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fBPAM_SUCCESS\fR\fR
262 .ad
263 .RS 20n
264 Successfully obtained Kerberos credentials .
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBPAM_SYSTEM_ERR\fR\fR
271 .ad
272 .RS 20n
273 System error.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBPAM_USER_UNKNOWN\fR\fR
280 .ad
281 .RS 20n
282 An unknown Kerberos principal was requested.
283 .RE
285 .sp
286 .LP
287 The following error codes are returned for \fBpam_sm_setcred()\fR:
288 .sp
289 .ne 2
290 .na
291 \fB\fBPAM_AUTH_ERR\fR\fR
292 .ad
293 .RS 18n
294 Authentication failure.
295 .RE
297 .sp
298 .ne 2
299 .na
300 \fB\fBPAM_BUF_ERR\fR\fR
301 .ad
302 .RS 18n
303 Memory buffer error.
304 .RE
306 .sp
307 .ne 2
308 .na
309 \fB\fBPAM_IGNORE\fR\fR
310 .ad
311 .RS 18n
312 The user is "\fBroot\fR" and the root key exists in the default keytab.
313 .RE
315 .sp
316 .ne 2
317 .na
318 \fB\fBPAM_SYSTEM_ERR\fR\fR
319 .ad
320 .RS 18n
321 System error.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBPAM_SUCCESS\fR\fR
328 .ad
329 .RS 18n
330 Successfully modified the Kerberos credential cache.
331 .RE
333 .sp
334 .LP
335 The following error codes are returned for \fBpam_sm_acct_mgmt()\fR:
336 .sp
337 .ne 2
338 .na
339 \fB\fBPAM_AUTH_ERR\fR\fR
340 .ad
341 .RS 24n
342 Authentication failure.
343 .RE
345 .sp
346 .ne 2
347 .na
348 \fB\fBPAM_IGNORE\fR\fR
349 .ad
350 .RS 24n
351 Kerberos service module \fBpam_sm_authenticate()\fR was never called, or the
352 user is "\fBroot\fR" and the root key exists in the default keytab.
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR
359 .ad
360 .RS 24n
361 Obtain new authentication token from the user.
362 .RE
364 .sp
365 .ne 2
366 .na
367 \fB\fBPAM_SERVICE_ERR\fR\fR
368 .ad
369 .RS 24n
370 Error in underlying service module.
371 .RE
373 .sp
374 .ne 2
375 .na
376 \fB\fBPAM_SUCCESS\fR\fR
377 .ad
378 .RS 24n
379 Kerberos principal account is valid.
380 .RE
382 .sp
383 .ne 2
384 .na
385 \fB\fBPAM_SYSTEM_ERR\fR\fR
386 .ad
387 .RS 24n
388 System error.
389 .RE
391 .sp
392 .ne 2
393 .na
394 \fB\fBPAM_USER_UNKNOWN\fR\fR
395 .ad
396 .RS 24n
397 An unknown Kerberos principal was requested.
398 .RE
400 .sp
401 .LP
402 The following error code is returned for \fBpam_sm_open_session()\fR and
403 \fBpam_sm_close_session()\fR:
404 .sp
405 .ne 2
406 .na
407 \fB\fBPAM_IGNORE\fR\fR
408 .ad
409 .RS 14n
410 These two functions are null functions in \fBpam_krb5\fR:
411 .RE
413 .sp
414 .LP
415 The following error codes are returned for \fBpam_sm_chauthtok()\fR:
416 .sp
417 .ne 2
418 .na
419 \fB\fBPAM_AUTH_ERR\fR\fR
420 .ad
421 .RS 24n
422 Authentication failure.
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBPAM_IGNORE\fR\fR
429 .ad
430 .RS 24n
431 The user has not been authenticated by Kerberos service module
432 \fBpam_sm_authenticate()\fR, or the user is "\fBroot\fR" and the root key
433 exists in the default keytab.
434 .RE
436 .sp
437 .ne 2
438 .na
439 \fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR
440 .ad
441 .RS 24n
442 User's Kerberos password has expired.
443 .RE
445 .sp
446 .ne 2
447 .na
448 \fB\fBPAM_SERVICE_ERR\fR\fR
449 .ad
450 .RS 24n
451 Error in module. At least one input parameter is missing.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBPAM_SYSTEM_ERR\fR\fR
458 .ad
459 .RS 24n
460 System error.
461 .RE
463 .sp
464 .ne 2
465 .na
466 \fB\fBPAM_USER_UNKNOWN\fR\fR
467 .ad
468 .RS 24n
469 An unknown Kerberos principal was requested.
470 .RE
472 .sp
473 .ne 2
474 .na
475 \fB\fBPAM_SUCCESS\fR\fR
476 .ad
477 .RS 24n
478 Successfully changed the user's Kerberos password.
479 .RE
481 .SH EXAMPLES
482 .LP
483 \fBExample 1 \fRAuthenticate Users Through Kerberos as First Choice
484 .sp
485 .LP
486 The following is an excerpt of a sample \fBpam.conf\fR configuration file that
487 authenticates users through the Kerberos authentication service and
488 authenticates through the Unix login only if the Kerberos authentication fails.
489 This arrangement is helpful when a majority of the users are networked by means
490 of Kerberos and when there are only a few non-Kerberos type user accounts, such
491 as root. The service illustrated below is for \fBdtlogin\fR.
493 .sp
494 .in +2
495 .nf
496 dtlogin auth requisite pam_smartcard.so.1
497 dtlogin auth requisite pam_authtok_get.so.1
498 dtlogin auth required pam_dhkeys.so.1
499 dtlogin auth required pam_unix_cred.so.1
500 dtlogin auth sufficient pam_krb5.so.1
501 dtlogin auth required pam_unix_auth.so.1
502 .fi
503 .in -2
505 .sp
506 .LP
507 Note that these changes should not be made to the existing \fBkrlogin\fR,
508 \fBkrsh\fR, and \fBktelnet\fR service entries. Those services require Kerberos
509 authentication, so using a seemingly sufficient control flag would not provide
510 the necessary functionality for privacy and integrity. There should be no need
511 to change those entries.
513 .sp
514 .LP
515 The following entries check for password expiration when dealing with Kerberos
516 and Unix password aging policies:
518 .sp
519 .in +2
520 .nf
521 other account requisite pam_roles.so.1
522 other account required pam_unix_account.so.1
523 other account required pam_krb5.so.1
524 .fi
525 .in -2
527 .sp
528 .LP
529 The following entries would change the Kerberos password of the user and
530 continue to change the Unix login password only if the Kerberos password change
531 had failed:
533 .sp
534 .in +2
535 .nf
536 other password required pam_dhkeys.so.1
537 other password requisite pam_authtok_get.so.1
538 other password requisite pam_authtok_check.so.1
539 other password sufficient pam_krb5.so.1
540 other password required pam_authtok_store.so.1
541 .fi
542 .in -2
544 .sp
545 .LP
546 When changing Kerberos based user's password, use \fBkpasswd\fR(1). When
547 changing a non-Kerberos user's password, it is recommended that the repository
548 is specified (\fB-r\fR) with the \fBpasswd\fR(1) command.
550 .LP
551 \fBExample 2 \fRAuthenticate Users Through Kerberos Only
552 .sp
553 .LP
554 The following example allows authentication only to users that have
555 Kerberos-based accounts.
557 .sp
558 .in +2
559 .nf
560 dtlogin auth requisite pam_smartcard.so.1
561 dtlogin auth requisite pam_authtok_get.so.1
562 dtlogin auth required pam_dhkeys.so.1
563 dtlogin auth required pam_unix_cred.so.1
564 dtlogin auth binding pam_krb5.so.1
565 dtlogin auth required pam_unix_auth.so.1
566 .fi
567 .in -2
569 .sp
570 .LP
571 Typically, you would have another service specified in the \fBpam.conf\fR file
572 that would allow local users, such as database, web server, system
573 administrator accounts, to log in to the host machine. For example, the service
574 name "login" could be used for these users. Note that these users should not
575 belong to any roles.
577 .sp
578 .LP
579 The rest of the module types look similar to that shown in the previous
580 example:
582 .sp
583 .in +2
584 .nf
585 other account requisite pam_roles.so.1
586 other account required pam_unix_account.so.1
587 other account required pam_krb5.so.1
588 .fi
589 .in -2
591 .sp
592 .LP
593 With binding specified in the following, it is important that non-Kerberos
594 users specify the repository in which they reside using the \fB-r\fR option
595 with the \fBpasswd\fR(1) command. This configuration is also based on the
596 assumptions that:
598 .RS +4
599 .TP
600 .ie t \(bu
601 .el o
602 Kerberos users maintain only their Kerberos passwords;
603 .RE
604 .RS +4
605 .TP
606 .ie t \(bu
607 .el o
608 changing their Unix password is not necessary, given that they are
609 authenticated only through their Kerberos passwords when logging in.
610 .RE
611 .sp
612 .in +2
613 .nf
614 other password required pam_dhkeys.so.1
615 other password requisite pam_authtok_get.so.1
616 other password requisite pam_authtok_check.so.1
617 other password binding pam_krb5.so.1
618 other password required pam_authtok_store.so.1
619 .fi
620 .in -2
622 .LP
623 \fBExample 3 \fRAuthenticate Through Kerberos Optionally
624 .sp
625 .LP
626 This configuration is helpful when the majority of users are non-Kerberos users
627 and would like to authenticate through Kerberos if they happened to exist in
628 the Kerberos database. The effect of this is similar to users voluntarily
629 executing \fBkinit\fR(1) after they have successfully logged in:
631 .sp
632 .in +2
633 .nf
634 dtlogin auth requisite pam_smartcard.so.1
635 dtlogin auth requisite pam_authtok_get.so.1
636 dtlogin auth required pam_dhkeys.so.1
637 dtlogin auth required pam_unix_cred.so.1
638 dtlogin auth required pam_unix_auth.so.1
639 dtlogin auth optional pam_krb5.so.1
640 .fi
641 .in -2
643 .sp
644 .LP
645 The rest of the configuration is as follows:
647 .sp
648 .in +2
649 .nf
650 other account requisite pam_roles.so.1
651 other account required pam_unix_account.so.1
652 other account required pam_krb5.so.1
654 other password required pam_dhkeys.so.1
655 other password requisite pam_authtok_get.so.1
656 other password requisite pam_authtok_check.so.1
657 other password required pam_authtok_store.so.1
658 other password optional pam_krb5.so.1
659 .fi
660 .in -2
662 .sp
663 .LP
664 Non-Kerberos users should specify their respective repositories by using the
665 \fB-r\fR option when changing their password with the \fBpasswd\fR(1) command.
667 .SH ATTRIBUTES
668 .sp
669 .LP
670 See \fBattributes\fR(5) for descriptions of the following attributes:
671 .sp
673 .sp
674 .TS
675 box;
676 c | c
677 l | l .
678 ATTRIBUTE TYPE ATTRIBUTE VALUE
679 _
680 Interface Stability Evolving
681 .TE
683 .SH SEE ALSO
684 .sp
685 .LP
686 \fBkdestroy\fR(1), \fBkinit\fR(1), \fBkpasswd\fR(1), \fBpasswd\fR(1),
687 \fBktkt_warnd\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_sm\fR(3PAM),
688 \fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM),
689 \fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM),
690 \fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C),
691 \fBpam.conf\fR(4), \fBattributes\fR(5), \fBkerberos\fR(5), \fBkrb5envvar\fR(5)
692 .SH NOTES
693 .sp
694 .LP
695 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
696 multi-threaded application uses its own \fBPAM\fR handle.
697 .sp
698 .LP
699 On successful acquisition of initial credentials (ticket-granting ticket),
700 \fBktkt_warnd\fR(1M) will be notified, to alert the user when the initial
701 credentials are about to expire.