|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| .github/ | H | - | - | 52 | 45 |
| ci/ | H | - | - | 435 | 272 |
| docs/ | H | - | - | 1,609 | 1,272 |
| m4/ | H | - | - | 1,134 | 1,066 |
| module/ | H | - | - | 4,428 | 2,702 |
| pam-util/ | H | - | - | 2,007 | 1,068 |
| portable/ | H | - | - | 1,659 | 767 |
| tests/ | H | - | - | 15,349 | 9,572 |
| .clang-format | H A D | 05-Jun-2025 | 943 | 31 | 29 |
| LICENSE | H A D | 05-Jun-2025 | 16.9 KiB | 345 | 321 |
| Makefile.am | H A D | 05-Jun-2025 | 10 KiB | 211 | 166 |
| NEWS | H A D | 05-Jun-2025 | 54.3 KiB | 1,216 | 915 |
| README | H A D | 05-Jun-2025 | 30.6 KiB | 642 | 508 |
| README.md | H A D | 05-Jun-2025 | 30.2 KiB | 666 | 545 |
| TODO | H A D | 05-Jun-2025 | 3.9 KiB | 102 | 72 |
| bootstrap | H A D | 05-Jun-2025 | 316 | 14 | 6 |
| configure.ac | H A D | 05-Jun-2025 | 5.1 KiB | 146 | 132 |
README
1 pam-krb5 4.11
2 (PAM module for Kerberos authentication)
3 Maintained by Russ Allbery <eagle@eyrie.org>
4
5 Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery
6 <eagle@eyrie.org>. Copyright 2009-2011 The Board of Trustees of the
7 Leland Stanford Junior University. Copyright 2005 Andres Salomon
8 <dilinger@debian.org>. Copyright 1999-2000 Frank Cusack
9 <fcusack@fcusack.com>. This software is distributed under a BSD-style
10 license. Please see the section LICENSE below for more information.
11
12BLURB
13
14 pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal.
15 It supports ticket refreshing by screen savers, configurable
16 authorization handling, authentication of non-local accounts for network
17 services, password changing, and password expiration, as well as all the
18 standard expected PAM features. It works correctly with OpenSSH, even
19 with ChallengeResponseAuthentication and PrivilegeSeparation enabled,
20 and supports extensive configuration either by PAM options or in
21 krb5.conf or both. PKINIT is supported with recent versions of both MIT
22 Kerberos and Heimdal and FAST is supported with recent MIT Kerberos.
23
24DESCRIPTION
25
26 pam-krb5 provides a Kerberos PAM module that supports authentication,
27 user ticket cache handling, simple authorization (via .k5login or
28 checking Kerberos principals against local usernames), and password
29 changing. It can be configured through either options in the PAM
30 configuration itself or through entries in the system krb5.conf file,
31 and it tries to work around PAM implementation flaws in commonly-used
32 PAM-enabled applications such as OpenSSH and xdm. It supports both
33 PKINIT and FAST to the extent that the underlying Kerberos libraries
34 support these features.
35
36 This is not the Kerberos PAM module maintained on Sourceforge and used
37 on Red Hat systems. It is an independent implementation that, if it
38 ever shared any common code, diverged long ago. It supports some
39 features that the Sourceforge module does not (particularly around
40 authorization), and does not support some options (particularly ones not
41 directly related to Kerberos) that it does. This module will never
42 support Kerberos v4 or AFS. For an AFS session module that works with
43 this module (or any other Kerberos PAM module), see pam-afs-session [1].
44
45 [1] https://www.eyrie.org/~eagle/software/pam-afs-session/
46
47 If there are other options besides AFS and Kerberos v4 support from the
48 Sourceforge PAM module that you're missing in this module, please let me
49 know.
50
51REQUIREMENTS
52
53 Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal
54 are supported. MIT Keberos 1.3 or later may be required; this module
55 has not been tested with earlier versions.
56
57 For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or
58 later are required. Earlier MIT Kerberos 1.6 releases have a bug in
59 their handling of PKINIT options. MIT Kerberos 1.12 or later is
60 required to use the use_pkinit PAM option.
61
62 For FAST (Flexible Authentication Secure Tunneling) support, MIT
63 Kerberos 1.7 or higher is required. For anonymous FAST support,
64 anonymous authentication (generally anonymous PKINIT) support is
65 required in both the Kerberos libraries and in the local KDC.
66
67 This module should work on Linux and build with gcc or clang. It may
68 still work on Solaris and build with the Sun C compiler, but I have only
69 tested it on Linux recently. There is beta-quality support for the AIX
70 NAS Kerberos implementation that has not been tested in years. Other
71 PAM implementations will probably require some porting, although
72 untested build system support is present for FreeBSD, Mac OS X, and
73 HP-UX. I personally can only test on Linux and rely on others to report
74 problems on other operating systems.
75
76 Old versions of OpenSSH are known to call pam_authenticate followed by
77 pam_setcred(PAM_REINITIALIZE_CRED) without first calling
78 pam_open_session, thereby requesting that an existing ticket cache be
79 renewed (similar to what a screensaver would want) rather than
80 requesting a new ticket cache be created. Since this behavior is
81 indistinguishable at the PAM level from a screensaver, pam-krb5 when
82 used with these old versions of OpenSSH will refresh the ticket cache of
83 the OpenSSH daemon rather than setting up a new ticket cache for the
84 user. The resulting ticket cache will have the correct permissions
85 (this is not a security concern), but will not be named correctly or
86 referenced in the user's environment and will be overwritten by the next
87 user login. The best solution to this problem is to upgrade OpenSSH.
88 I'm not sure exactly when this problem was fixed, but at the very least
89 OpenSSH 4.3 and later do not exhibit it.
90
91 To bootstrap from a Git checkout, or if you change the Automake files
92 and need to regenerate Makefile.in, you will need Automake 1.11 or
93 later. For bootstrap or if you change configure.ac or any of the m4
94 files it includes and need to regenerate configure or config.h.in, you
95 will need Autoconf 2.64 or later. Perl is also required to generate
96 manual pages from a fresh Git checkout.
97
98BUILDING AND INSTALLATION
99
100 You can build and install pam-krb5 with the standard commands:
101
102 ./configure
103 make
104 make install
105
106 If you are building from a Git clone, first run ./bootstrap in the
107 source directory to generate the build files. make install will
108 probably have to be done as root. Building outside of the source
109 directory is also supported, if you wish, by creating an empty directory
110 and then running configure with the correct relative path.
111
112 The module will be installed in /usr/local/lib/security by default, but
113 expect to have to override this using --libdir. The correct
114 installation path for PAM modules varies considerably between systems.
115 The module will always be installed in a subdirectory named security
116 under the specified value of --libdir. On Red Hat Linux, for example,
117 --libdir=/usr/lib64 is appropriate to install the module into the system
118 PAM directory. On Debian's amd64 architecture,
119 --libdir=/usr/lib/x86_64-linux-gnu would be correct.
120
121 Normally, configure will use krb5-config to determine the flags to use
122 to compile with your Kerberos libraries. To specify a particular
123 krb5-config script to use, either set the PATH_KRB5_CONFIG environment
124 variable or pass it to configure like:
125
126 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
127
128 If krb5-config isn't found, configure will look for the standard
129 Kerberos libraries in locations already searched by your compiler. If
130 the the krb5-config script first in your path is not the one
131 corresponding to the Kerberos libraries you want to use, or if your
132 Kerberos libraries and includes aren't in a location searched by default
133 by your compiler, you need to specify a different Kerberos installation
134 root via --with-krb5=PATH. For example:
135
136 ./configure --with-krb5=/usr/pubsw
137
138 You can also individually set the paths to the include directory and the
139 library directory with --with-krb5-include and --with-krb5-lib. You may
140 need to do this if Autoconf can't figure out whether to use lib, lib32,
141 or lib64 on your platform.
142
143 To not use krb5-config and force library probing even if there is a
144 krb5-config script on your path, set PATH_KRB5_CONFIG to a nonexistent
145 path:
146
147 ./configure PATH_KRB5_CONFIG=/nonexistent
148
149 krb5-config is not used and library probing is always done if either
150 --with-krb5-include or --with-krb5-lib are given.
151
152 Pass --enable-silent-rules to configure for a quieter build (similar to
153 the Linux kernel). Use make warnings instead of make to build with full
154 compiler warnings (requires either GCC or Clang and may require a
155 relatively current version of the compiler).
156
157 You can pass the --enable-reduced-depends flag to configure to try to
158 minimize the shared library dependencies encoded in the binaries. This
159 omits from the link line all the libraries included solely because other
160 libraries depend on them and instead links the programs only against
161 libraries whose APIs are called directly. This will only work with
162 shared libraries and will only work on platforms where shared libraries
163 properly encode their own dependencies (this includes most modern
164 platforms such as all Linux). It is intended primarily for building
165 packages for Linux distributions to avoid encoding unnecessary shared
166 library dependencies that make shared library migrations more difficult.
167 If none of the above made any sense to you, don't bother with this flag.
168
169TESTING
170
171 pam-krb5 comes with a comprehensive test suite, but it requires some
172 configuration in order to test anything other than low-level utility
173 functions. For the full test suite, you will need to have a running KDC
174 in which you can create two test accounts, one with admin access to the
175 other. Using a test KDC environment, if you have one, is recommended.
176
177 Follow the instructions in tests/config/README to configure the test
178 suite.
179
180 Now, you can run the test suite with:
181
182 make check
183
184 If a test fails, you can run a single test with verbose output via:
185
186 tests/runtests -o <name-of-test>
187
188 Do this instead of running the test program directly since it will
189 ensure that necessary environment variables are set up.
190
191 The default libkadm5clnt library on the system must match the
192 implementation of your KDC for the module/expired test to work, since
193 the two kadmin protocols are not compatible. If you use the MIT library
194 against a Heimdal server, the test will be skipped; if you use the
195 Heimdal library against an MIT server, the test suite may hang.
196
197 Several module/expired tests are expected to fail with Heimdal 1.5 due
198 to a bug in Heimdal with reauthenticating immediately after a
199 library-mediated password change of an expired password. This is fixed
200 in later releases of Heimdal.
201
202 To run the full test suite, Perl 5.10 or later is required. The
203 following additional Perl modules will be used if present:
204
205 * Test::Pod
206 * Test::Spelling
207
208 All are available on CPAN. Those tests will be skipped if the modules
209 are not available.
210
211 To enable tests that don't detect functionality problems but are used to
212 sanity-check the release, set the environment variable RELEASE_TESTING
213 to a true value. To enable tests that may be sensitive to the local
214 environment or that produce a lot of false positives without uncovering
215 many problems, set the environment variable AUTHOR_TESTING to a true
216 value.
217
218CONFIGURING
219
220 Just installing the module does not enable it or change anything about
221 your system authentication configuration. To use the module for all
222 system authentication on Debian systems, put something like:
223
224 auth sufficient pam_krb5.so minimum_uid=1000
225 auth required pam_unix.so try_first_pass nullok_secure
226
227 in /etc/pam.d/common-auth, something like:
228
229 session optional pam_krb5.so minimum_uid=1000
230 session required pam_unix.so
231
232 in /etc/pam.d/common-session, and something like:
233
234 account required pam_krb5.so minimum_uid=1000
235 account required pam_unix.so
236
237 in /etc/pam.d/common-account. The minimum_uid setting tells the PAM
238 module to pass on any users with a UID lower than 1000, thereby
239 bypassing Kerberos authentication for the root account and any system
240 accounts. You normally want to do this since otherwise, if the network
241 is down, the Kerberos authentication can time out and make it difficult
242 to log in as root and fix matters. This also avoids problems with
243 Kerberos principals that happen to match system accounts accidentally
244 getting access to those accounts.
245
246 Be sure to include the module in the session group as well as the auth
247 group. Without the session entry, the user's ticket cache will not be
248 created properly for ssh logins (among possibly others).
249
250 If your users should normally all use Kerberos passwords exclusively,
251 putting something like:
252
253 password sufficient pam_krb5.so minimum_uid=1000
254 password required pam_unix.so try_first_pass obscure md5
255
256 in /etc/pam.d/common-password will change users' passwords in Kerberos
257 by default and then only fall back on Unix if that doesn't work. (You
258 can make this tighter by using the more complex new-style PAM
259 configuration.) If you instead want to synchronize local and Kerberos
260 passwords and change them both at the same time, you can do something
261 like:
262
263 password required pam_unix.so obscure sha512
264 password required pam_krb5.so use_authtok minimum_uid=1000
265
266 If you have multiple environments that you want to synchronize and you
267 don't want password changes to continue if the Kerberos password change
268 fails, use the clear_on_fail option. For example:
269
270 password required pam_krb5.so clear_on_fail minimum_uid=1000
271 password required pam_unix.so use_authtok obscure sha512
272 password required pam_smbpass.so use_authtok
273
274 In this case, if pam_krb5 cannot change the password (due to password
275 strength rules on the KDC, for example), it will clear the stored
276 password (because of the clear_on_fail option), and since pam_unix and
277 pam_smbpass are both configured with use_authtok, they will both fail.
278 clear_on_fail is not the default because it would interfere with the
279 more common pattern of falling back to local passwords if the user
280 doesn't exist in Kerberos.
281
282 If you use a more complex configuration with the Linux PAM [] syntax for
283 the session and account groups, note that pam_krb5 returns a status of
284 ignore, not success, if the user didn't log on with Kerberos. You may
285 need to handle that explicitly with ignore=ignore in your action list.
286
287 There are many, many other possibilities. See the Linux PAM
288 documentation for all the configuration options.
289
290 On Red Hat systems, modify /etc/pam.d/system-auth instead, which
291 contains all of the configuration for the different stacks.
292
293 You can also use pam-krb5 only for specific services. In that case,
294 modify the files in /etc/pam.d for that particular service to use
295 pam_krb5.so for authentication. For services that are using passwords
296 over TLS to authenticate users, you may want to use the ignore_k5login
297 and no_ccache options to the authenticate module. .k5login
298 authorization is only meaningful for local accounts and ticket caches
299 are usually (although not always) only useful for interactive sessions.
300
301 Configuring the module for Solaris is both simpler and less flexible,
302 since Solaris (at least Solaris 8 and 9, which are the last versions of
303 Solaris with which this module was extensively tested) use a single
304 /etc/pam.conf file that contains configuration for all programs. For
305 console login on Solaris, try something like:
306
307 login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100
308 login auth required /usr/lib/security/pam_unix_auth.so.1 use_first_pass
309 login account required /usr/local/lib/security/pam_krb5.so minimum_uid=100
310 login account required /usr/lib/security/pam_unix_account.so.1
311 login session required /usr/local/lib/security/pam_krb5.so retain_after_close minimum_uid=100
312 login session required /usr/lib/security/pam_unix_session.so.1
313
314 A similar configuration could be used for other services, such as ssh.
315 See the pam.conf(5) man page for more information. When using this
316 module with Solaris login (at least on Solaris 8 and 9), you will
317 probably also need to add retain_after_close to the PAM configuration to
318 avoid having the user's credentials deleted before they are logged in.
319
320 The Solaris Kerberos library reportedly does not support prompting for a
321 password change of an expired account during authentication. Supporting
322 password change for expired accounts on Solaris with native Kerberos may
323 therefore require setting the defer_pwchange or force_pwchange option
324 for selected login applications. See the description and warnings about
325 that option in the pam_krb5(5) man page.
326
327 Some configuration options may be put in the krb5.conf file used by your
328 Kerberos libraries (usually /etc/krb5.conf or /usr/local/etc/krb5.conf)
329 instead or in addition to the PAM configuration. See the man page for
330 more details.
331
332 The Kerberos library, via pam-krb5, will prompt the user to change their
333 password if their password is expired, but when using OpenSSH, this will
334 only work when ChallengeResponseAuthentication is enabled. Unless this
335 option is enabled, OpenSSH doesn't pass PAM messages to the user and can
336 only respond to a simple password prompt.
337
338 If you are using MIT Kerberos, be aware that users whose passwords are
339 expired will not be prompted to change their password unless the KDC
340 configuration for your realm in [realms] in krb5.conf contains a
341 master_kdc setting or, if using DNS SRV records, you have a DNS entry
342 for _kerberos-master as well as _kerberos.
343
344DEBUGGING
345
346 The first step when debugging any problems with this module is to add
347 debug to the PAM options for the module (either in the PAM configuration
348 or in krb5.conf). This will significantly increase the logging from the
349 module and should provide a trace of exactly what failed and any
350 available error information.
351
352 Many Kerberos authentication problems are due to configuration issues in
353 krb5.conf. If pam-krb5 doesn't work, first check that kinit works on
354 the same system. That will test your basic Kerberos configuration. If
355 the system has a keytab file installed that's readable by the process
356 doing authentication via PAM, make sure that the keytab is current and
357 contains a key for host/<system> where <system> is the fully-qualified
358 hostname. pam-krb5 prevents KDC spoofing by checking the user's
359 credentials when possible, but this means that if a keytab is present it
360 must be correct or authentication will fail. You can check the keytab
361 with klist -k and kinit -k.
362
363 Be sure that all libraries and modules, including PAM modules, loaded by
364 a program use the same Kerberos libraries. Sometimes programs that use
365 PAM, such as current versions of OpenSSH, also link against Kerberos
366 directly. If your sshd is linked against one set of Kerberos libraries
367 and pam-krb5 is linked against a different set of Kerberos libraries,
368 this will often cause problems (such as segmentation faults, bus errors,
369 assertions, or other strange behavior). Similar issues apply to the
370 com_err library or any other library used by both modules and shared
371 libraries and by the application that loads them. If your OS ships
372 Kerberos libraries, it's usually best if possible to build all Kerberos
373 software on the system against those libraries.
374
375IMPLEMENTATION NOTES
376
377 The normal sequence of actions taken for a user login is:
378
379 pam_authenticate
380 pam_setcred(PAM_ESTABLISH_CRED)
381 pam_open_session
382 pam_acct_mgmt
383
384 and then at logout:
385
386 pam_close_session
387
388 followed by closing the open PAM session. The corresponding pam_sm_*
389 functions in this module are called when an application calls those
390 public interface functions. Not all applications call all of those
391 functions, or in particularly that order, although pam_authenticate is
392 always first and has to be.
393
394 When pam_authenticate is called, pam-krb5 creates a temporary ticket
395 cache in /tmp and sets the PAM environment variable PAM_KRB5CCNAME to
396 point to it. This ticket cache will be automatically destroyed when the
397 PAM session is closed and is there only to pass the initial credentials
398 to the call to pam_setcred. The module would use a memory cache, but
399 memory caches will only work if the application preserves the PAM
400 environment between the calls to pam_authenticate and pam_setcred. Most
401 do, but OpenSSH notoriously does not and calls pam_authenticate in a
402 subprocess, so this method is used to pass the tickets to the
403 pam_setcred call in a different process.
404
405 pam_authenticate does a complete authentication, including checking the
406 resulting TGT by obtaining a service ticket for the local host if
407 possible, but this requires read access to the system keytab. If the
408 keytab doesn't exist, can't be read, or doesn't include the appropriate
409 credentials, the default is to accept the authentication. This can be
410 controlled by setting verify_ap_req_nofail to true in [libdefaults] in
411 /etc/krb5.conf. pam_authenticate also does a basic authorization check,
412 by default calling krb5_kuserok (which uses ~/.k5login if available and
413 falls back to checking that the principal corresponds to the account
414 name). This can be customized with several options documented in the
415 pam_krb5(5) man page.
416
417 pam-krb5 treats pam_open_session and pam_setcred(PAM_ESTABLISH_CRED) as
418 synonymous, as some applications call one and some call the other. Both
419 copy the initial credentials from the temporary cache into a permanent
420 cache for this session and set KRB5CCNAME in the environment. It will
421 remember when the credential cache has been established and then avoid
422 doing any duplicate work afterwards, since some applications call
423 pam_setcred or pam_open_session multiple times (most notably X.Org 7 and
424 earlier xdm, which also throws away the module settings the last time it
425 calls them).
426
427 pam_acct_mgmt finds the ticket cache, reads it in to obtain the
428 authenticated principal, and then does is another authorization check
429 against .k5login or the local account name as described above.
430
431 After the call to pam_setcred or pam_open_session, the ticket cache will
432 be destroyed whenever the calling application either destroys the PAM
433 environment or calls pam_close_session, which it should do on user
434 logout.
435
436 The normal sequence of events when refreshing a ticket cache (such as
437 inside a screensaver) is:
438
439 pam_authenticate
440 pam_setcred(PAM_REINITIALIZE_CRED)
441 pam_acct_mgmt
442
443 (PAM_REFRESH_CRED may be used instead.) Authentication proceeds as
444 above. At the pam_setcred stage, rather than creating a new ticket
445 cache, the module instead finds the current ticket cache (from the
446 KRB5CCNAME environment variable or the default ticket cache location
447 from the Kerberos library) and then reinitializes it with the
448 credentials from the temporary pam_authenticate ticket cache. When
449 refreshing a ticket cache, the application should not open a session.
450 Calling pam_acct_mgmt is optional; pam-krb5 doesn't do anything
451 different when it's called in this case.
452
453 If pam_authenticate apparently didn't succeed, or if an account was
454 configured to be ignored via ignore_root or minimum_uid, pam_setcred
455 (and therefore pam_open_session) and pam_acct_mgmt return PAM_IGNORE,
456 which tells the PAM library to proceed as if that module wasn't listed
457 in the PAM configuration at all. pam_authenticate, however, returns
458 failure in the ignored user case by default, since otherwise a
459 configuration using ignore_root with pam-krb5 as the only PAM module
460 would allow anyone to log in as root without a password. There doesn't
461 appear to be a case where returning PAM_IGNORE instead would improve the
462 module's behavior, but if you know of a case, please let me know.
463
464 By default, pam_authenticate intentionally does not follow the PAM
465 standard for handling expired accounts and instead returns failure from
466 pam_authenticate unless the Kerberos libraries are able to change the
467 account password during authentication. Too many applications either do
468 not call pam_acct_mgmt or ignore its exit status. The fully correct PAM
469 behavior (returning success from pam_authenticate and
470 PAM_NEW_AUTHTOK_REQD from pam_acct_mgmt) can be enabled with the
471 defer_pwchange option.
472
473 The defer_pwchange option is unfortunately somewhat tricky to implement.
474 In this case, the calling sequence is:
475
476 pam_authenticate
477 pam_acct_mgmt
478 pam_chauthtok
479 pam_setcred
480 pam_open_session
481
482 During the first pam_authenticate, we can't obtain credentials and
483 therefore a ticket cache since the password is expired. But
484 pam_authenticate isn't called again after pam_chauthtok, so
485 pam_chauthtok has to create a ticket cache. We however don't want it to
486 do this for the normal password change (passwd) case.
487
488 What we do is set a flag in our PAM data structure saying that we're
489 processing an expired password, and pam_chauthtok, if it sees that flag,
490 redoes the authentication with password prompting disabled after it
491 finishes changing the password.
492
493 Unfortunately, when handling password changes this way, pam_chauthtok
494 will always have to prompt the user for their current password again
495 even though they just typed it. This is because the saved
496 authentication tokens are cleared after pam_authenticate returns, for
497 security reasons. We could hack around this by saving the password in
498 our PAM data structure, but this would let the application gain access
499 to it (exactly what the clearing is intended to prevent) and breaks a
500 PAM library guarantee. We could also work around this by having
501 pam_authenticate get the kadmin/changepw authenticator in the expired
502 password case and store it for pam_chauthtok, but it doesn't seem worth
503 the hassle.
504
505HISTORY AND ACKNOWLEDGEMENTS
506
507 Originally written by Frank Cusack <fcusack@fcusack.com>, with the
508 following acknowledgement:
509
510 Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King
511 <curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all
512 of whom have written and made available Kerberos 4/5 modules.
513 Although no code in this module is directly from these author's
514 modules, (except the get_user_info() routine in support.c; derived
515 from whichever of these authors originally wrote the first module the
516 other 2 copied from), it was extremely helpful to look over their code
517 which aided in my design.
518
519 The module was then patched for the FreeBSD ports collection with
520 additional modifications by unknown maintainers and then was modified by
521 Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux.
522
523 It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian
524 and improved and modified by him and later by Russ Allbery to fix bugs
525 and add additional features. It was then adopted by Andres Salomon, who
526 added support for refreshing credentials.
527
528 The current distribution is maintained by Russ Allbery, who also added
529 support for reading configuration from krb5.conf, added many features
530 for compatibility with the Sourceforge module, commented and
531 standardized the formatting of the code, and overhauled the
532 documentation.
533
534 Thanks to Douglas E. Engert for the initial implementation of PKINIT
535 support. I have since modified and reworked it extensively, so any bugs
536 or compilation problems are my fault.
537
538 Thanks to Markus Moeller for lots of debugging and multiple patches and
539 suggestions for improved portability.
540
541 Thanks to Booker Bense for the implementation of the alt_auth_map
542 option.
543
544 Thanks to Sam Hartman for the FAST support implementation.
545
546SUPPORT
547
548 The pam-krb5 web page at:
549
550 https://www.eyrie.org/~eagle/software/pam-krb5/
551
552 will always have the current version of this package, the current
553 documentation, and pointers to any additional resources.
554
555 For bug tracking, use the issue tracker on GitHub:
556
557 https://github.com/rra/pam-krb5/issues
558
559 However, please be aware that I tend to be extremely busy and work
560 projects often take priority. I'll save your report and get to it as
561 soon as I can, but it may take me a couple of months.
562
563SOURCE REPOSITORY
564
565 pam-krb5 is maintained using Git. You can access the current source on
566 GitHub at:
567
568 https://github.com/rra/pam-krb5
569
570 or by cloning the repository at:
571
572 https://git.eyrie.org/git/kerberos/pam-krb5.git
573
574 or view the repository via the web at:
575
576 https://git.eyrie.org/?p=kerberos/pam-krb5.git
577
578 The eyrie.org repository is the canonical one, maintained by the author,
579 but using GitHub is probably more convenient for most purposes. Pull
580 requests are gratefully reviewed and normally accepted.
581
582LICENSE
583
584 The pam-krb5 package as a whole is covered by the following copyright
585 statement and license:
586
587 Copyright 2005-2010, 2014-2015, 2017, 2020-2021
588 Russ Allbery <eagle@eyrie.org>
589 Copyright 2009-2011
590 The Board of Trustees of the Leland Stanford Junior University
591 Copyright 2005 Andres Salomon <dilinger@debian.org>
592 Copyright 1999-2000 Frank Cusack <fcusack@fcusack.com>
593
594 Redistribution and use in source and binary forms, with or without
595 modification, are permitted provided that the following conditions are
596 met:
597
598 1. Redistributions of source code must retain the above copyright
599 notice, and the entire permission notice in its entirety, including
600 the disclaimer of warranties.
601
602 2. Redistributions in binary form must reproduce the above copyright
603 notice, this list of conditions and the following disclaimer in the
604 documentation and/or other materials provided with the
605 distribution.
606
607 3. The name of the author may not be used to endorse or promote
608 products derived from this software without specific prior written
609 permission.
610
611 ALTERNATIVELY, this product may be distributed under the terms of the
612 GNU General Public License, in which case the provisions of the GPL
613 are required INSTEAD OF the above restrictions. (This clause is
614 necessary due to a potential bad interaction between the GPL and the
615 restrictions contained in a BSD-style copyright.)
616
617 THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
618 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
619 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
620 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
621 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
622 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
623 OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
624 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
625 TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
626 USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
627 DAMAGE.
628
629 Some files in this distribution are individually released under
630 different licenses, all of which are compatible with the above general
631 package license but which may require preservation of additional
632 notices. All required notices, and detailed information about the
633 licensing of each file, are recorded in the LICENSE file.
634
635 Files covered by a license with an assigned SPDX License Identifier
636 include SPDX-License-Identifier tags to enable automated processing of
637 license information. See https://spdx.org/licenses/ for more
638 information.
639
640 For any copyright range specified by files in this package as YYYY-ZZZZ,
641 the range specifies every single year in that closed interval.
642
README.md
1# pam-krb5
2
3[](https://github.com/rra/pam-krb5/actions)
5[](https://tracker.debian.org/pkg/libpam-krb5)
7
8Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery
9<eagle@eyrie.org>. Copyright 2009-2011 The Board of Trustees of the
10Leland Stanford Junior University. Copyright 2005 Andres Salomon
11<dilinger@debian.org>. Copyright 1999-2000 Frank Cusack
12<fcusack@fcusack.com>. This software is distributed under a BSD-style
13license. Please see the section [License](#license) below for more
14information.
15
16## Blurb
17
18pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It
19supports ticket refreshing by screen savers, configurable authorization
20handling, authentication of non-local accounts for network services,
21password changing, and password expiration, as well as all the standard
22expected PAM features. It works correctly with OpenSSH, even with
23ChallengeResponseAuthentication and PrivilegeSeparation enabled, and
24supports extensive configuration either by PAM options or in krb5.conf or
25both. PKINIT is supported with recent versions of both MIT Kerberos and
26Heimdal and FAST is supported with recent MIT Kerberos.
27
28## Description
29
30pam-krb5 provides a Kerberos PAM module that supports authentication, user
31ticket cache handling, simple authorization (via .k5login or checking
32Kerberos principals against local usernames), and password changing. It
33can be configured through either options in the PAM configuration itself
34or through entries in the system krb5.conf file, and it tries to work
35around PAM implementation flaws in commonly-used PAM-enabled applications
36such as OpenSSH and xdm. It supports both PKINIT and FAST to the extent
37that the underlying Kerberos libraries support these features.
38
39This is not the Kerberos PAM module maintained on Sourceforge and used on
40Red Hat systems. It is an independent implementation that, if it ever
41shared any common code, diverged long ago. It supports some features that
42the Sourceforge module does not (particularly around authorization), and
43does not support some options (particularly ones not directly related to
44Kerberos) that it does. This module will never support Kerberos v4 or
45AFS. For an AFS session module that works with this module (or any other
46Kerberos PAM module), see
47[pam-afs-session](https://www.eyrie.org/~eagle/software/pam-afs-session/).
48
49If there are other options besides AFS and Kerberos v4 support from the
50Sourceforge PAM module that you're missing in this module, please let me
51know.
52
53## Requirements
54
55Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal
56are supported. MIT Keberos 1.3 or later may be required; this module has
57not been tested with earlier versions.
58
59For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later
60are required. Earlier MIT Kerberos 1.6 releases have a bug in their
61handling of PKINIT options. MIT Kerberos 1.12 or later is required to use
62the use_pkinit PAM option.
63
64For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos
651.7 or higher is required. For anonymous FAST support, anonymous
66authentication (generally anonymous PKINIT) support is required in both
67the Kerberos libraries and in the local KDC.
68
69This module should work on Linux and build with gcc or clang. It may
70still work on Solaris and build with the Sun C compiler, but I have only
71tested it on Linux recently. There is beta-quality support for the AIX
72NAS Kerberos implementation that has not been tested in years. Other PAM
73implementations will probably require some porting, although untested
74build system support is present for FreeBSD, Mac OS X, and HP-UX. I
75personally can only test on Linux and rely on others to report problems on
76other operating systems.
77
78Old versions of OpenSSH are known to call `pam_authenticate` followed by
79`pam_setcred(PAM_REINITIALIZE_CRED)` without first calling
80`pam_open_session`, thereby requesting that an existing ticket cache be
81renewed (similar to what a screensaver would want) rather than requesting
82a new ticket cache be created. Since this behavior is indistinguishable
83at the PAM level from a screensaver, pam-krb5 when used with these old
84versions of OpenSSH will refresh the ticket cache of the OpenSSH daemon
85rather than setting up a new ticket cache for the user. The resulting
86ticket cache will have the correct permissions (this is not a security
87concern), but will not be named correctly or referenced in the user's
88environment and will be overwritten by the next user login. The best
89solution to this problem is to upgrade OpenSSH. I'm not sure exactly when
90this problem was fixed, but at the very least OpenSSH 4.3 and later do not
91exhibit it.
92
93To bootstrap from a Git checkout, or if you change the Automake files and
94need to regenerate Makefile.in, you will need Automake 1.11 or later. For
95bootstrap or if you change configure.ac or any of the m4 files it includes
96and need to regenerate configure or config.h.in, you will need Autoconf
972.64 or later. Perl is also required to generate manual pages from a
98fresh Git checkout.
99
100## Building and Installation
101
102You can build and install pam-krb5 with the standard commands:
103
104```
105 ./configure
106 make
107 make install
108```
109
110If you are building from a Git clone, first run `./bootstrap` in the
111source directory to generate the build files. `make install` will
112probably have to be done as root. Building outside of the source
113directory is also supported, if you wish, by creating an empty directory
114and then running configure with the correct relative path.
115
116The module will be installed in `/usr/local/lib/security` by default, but
117expect to have to override this using `--libdir`. The correct
118installation path for PAM modules varies considerably between systems.
119The module will always be installed in a subdirectory named `security`
120under the specified value of `--libdir`. On Red Hat Linux, for example,
121`--libdir=/usr/lib64` is appropriate to install the module into the system
122PAM directory. On Debian's amd64 architecture,
123`--libdir=/usr/lib/x86_64-linux-gnu` would be correct.
124
125Normally, configure will use `krb5-config` to determine the flags to use
126to compile with your Kerberos libraries. To specify a particular
127`krb5-config` script to use, either set the `PATH_KRB5_CONFIG` environment
128variable or pass it to configure like:
129
130```
131 ./configure PATH_KRB5_CONFIG=/path/to/krb5-config
132```
133
134If `krb5-config` isn't found, configure will look for the standard
135Kerberos libraries in locations already searched by your compiler. If the
136the `krb5-config` script first in your path is not the one corresponding
137to the Kerberos libraries you want to use, or if your Kerberos libraries
138and includes aren't in a location searched by default by your compiler,
139you need to specify a different Kerberos installation root via
140`--with-krb5=PATH`. For example:
141
142```
143 ./configure --with-krb5=/usr/pubsw
144```
145
146You can also individually set the paths to the include directory and the
147library directory with `--with-krb5-include` and `--with-krb5-lib`. You
148may need to do this if Autoconf can't figure out whether to use `lib`,
149`lib32`, or `lib64` on your platform.
150
151To not use `krb5-config` and force library probing even if there is a
152`krb5-config` script on your path, set `PATH_KRB5_CONFIG` to a nonexistent
153path:
154
155```
156 ./configure PATH_KRB5_CONFIG=/nonexistent
157```
158
159`krb5-config` is not used and library probing is always done if either
160`--with-krb5-include` or `--with-krb5-lib` are given.
161
162Pass `--enable-silent-rules` to configure for a quieter build (similar to
163the Linux kernel). Use `make warnings` instead of `make` to build with
164full GCC compiler warnings (requires either GCC or Clang and may require a
165relatively current version of the compiler).
166
167You can pass the `--enable-reduced-depends` flag to configure to try to
168minimize the shared library dependencies encoded in the binaries. This
169omits from the link line all the libraries included solely because other
170libraries depend on them and instead links the programs only against
171libraries whose APIs are called directly. This will only work with shared
172libraries and will only work on platforms where shared libraries properly
173encode their own dependencies (this includes most modern platforms such as
174all Linux). It is intended primarily for building packages for Linux
175distributions to avoid encoding unnecessary shared library dependencies
176that make shared library migrations more difficult. If none of the above
177made any sense to you, don't bother with this flag.
178
179## Testing
180
181pam-krb5 comes with a comprehensive test suite, but it requires some
182configuration in order to test anything other than low-level utility
183functions. For the full test suite, you will need to have a running KDC
184in which you can create two test accounts, one with admin access to the
185other. Using a test KDC environment, if you have one, is recommended.
186
187Follow the instructions in `tests/config/README` to configure the test
188suite.
189
190Now, you can run the test suite with:
191
192```
193 make check
194```
195
196If a test fails, you can run a single test with verbose output via:
197
198```
199 tests/runtests -o <name-of-test>
200```
201
202Do this instead of running the test program directly since it will ensure
203that necessary environment variables are set up.
204
205The default libkadm5clnt library on the system must match the
206implementation of your KDC for the module/expired test to work, since the
207two kadmin protocols are not compatible. If you use the MIT library
208against a Heimdal server, the test will be skipped; if you use the Heimdal
209library against an MIT server, the test suite may hang.
210
211Several `module/expired` tests are expected to fail with Heimdal 1.5 due
212to a bug in Heimdal with reauthenticating immediately after a
213library-mediated password change of an expired password. This is fixed in
214later releases of Heimdal.
215
216To run the full test suite, Perl 5.10 or later is required. The following
217additional Perl modules will be used if present:
218
219* Test::Pod
220* Test::Spelling
221
222All are available on CPAN. Those tests will be skipped if the modules are
223not available.
224
225To enable tests that don't detect functionality problems but are used to
226sanity-check the release, set the environment variable `RELEASE_TESTING`
227to a true value. To enable tests that may be sensitive to the local
228environment or that produce a lot of false positives without uncovering
229many problems, set the environment variable `AUTHOR_TESTING` to a true
230value.
231
232## Configuring
233
234Just installing the module does not enable it or change anything about
235your system authentication configuration. To use the module for all
236system authentication on Debian systems, put something like:
237
238```
239 auth sufficient pam_krb5.so minimum_uid=1000
240 auth required pam_unix.so try_first_pass nullok_secure
241```
242
243in `/etc/pam.d/common-auth`, something like:
244
245```
246 session optional pam_krb5.so minimum_uid=1000
247 session required pam_unix.so
248```
249
250in `/etc/pam.d/common-session`, and something like:
251
252```
253 account required pam_krb5.so minimum_uid=1000
254 account required pam_unix.so
255```
256
257in `/etc/pam.d/common-account`. The `minimum_uid` setting tells the PAM
258module to pass on any users with a UID lower than 1000, thereby bypassing
259Kerberos authentication for the root account and any system accounts. You
260normally want to do this since otherwise, if the network is down, the
261Kerberos authentication can time out and make it difficult to log in as
262root and fix matters. This also avoids problems with Kerberos principals
263that happen to match system accounts accidentally getting access to those
264accounts.
265
266Be sure to include the module in the session group as well as the auth
267group. Without the session entry, the user's ticket cache will not be
268created properly for ssh logins (among possibly others).
269
270If your users should normally all use Kerberos passwords exclusively,
271putting something like:
272
273```
274 password sufficient pam_krb5.so minimum_uid=1000
275 password required pam_unix.so try_first_pass obscure md5
276```
277
278in `/etc/pam.d/common-password` will change users' passwords in Kerberos
279by default and then only fall back on Unix if that doesn't work. (You can
280make this tighter by using the more complex new-style PAM configuration.)
281If you instead want to synchronize local and Kerberos passwords and change
282them both at the same time, you can do something like:
283
284```
285 password required pam_unix.so obscure sha512
286 password required pam_krb5.so use_authtok minimum_uid=1000
287```
288
289If you have multiple environments that you want to synchronize and you
290don't want password changes to continue if the Kerberos password change
291fails, use the `clear_on_fail` option. For example:
292
293```
294 password required pam_krb5.so clear_on_fail minimum_uid=1000
295 password required pam_unix.so use_authtok obscure sha512
296 password required pam_smbpass.so use_authtok
297```
298
299In this case, if `pam_krb5` cannot change the password (due to password
300strength rules on the KDC, for example), it will clear the stored password
301(because of the `clear_on_fail` option), and since `pam_unix` and
302`pam_smbpass` are both configured with `use_authtok`, they will both fail.
303`clear_on_fail` is not the default because it would interfere with the
304more common pattern of falling back to local passwords if the user doesn't
305exist in Kerberos.
306
307If you use a more complex configuration with the Linux PAM `[]` syntax for
308the session and account groups, note that `pam_krb5` returns a status of
309ignore, not success, if the user didn't log on with Kerberos. You may
310need to handle that explicitly with `ignore=ignore` in your action list.
311
312There are many, many other possibilities. See the Linux PAM documentation
313for all the configuration options.
314
315On Red Hat systems, modify `/etc/pam.d/system-auth` instead, which
316contains all of the configuration for the different stacks.
317
318You can also use pam-krb5 only for specific services. In that case,
319modify the files in `/etc/pam.d` for that particular service to use
320`pam_krb5.so` for authentication. For services that are using passwords
321over TLS to authenticate users, you may want to use the `ignore_k5login`
322and `no_ccache` options to the authenticate module. `.k5login`
323authorization is only meaningful for local accounts and ticket caches are
324usually (although not always) only useful for interactive sessions.
325
326Configuring the module for Solaris is both simpler and less flexible,
327since Solaris (at least Solaris 8 and 9, which are the last versions of
328Solaris with which this module was extensively tested) use a single
329`/etc/pam.conf` file that contains configuration for all programs. For
330console login on Solaris, try something like:
331
332```
333 login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100
334 login auth required /usr/lib/security/pam_unix_auth.so.1 use_first_pass
335 login account required /usr/local/lib/security/pam_krb5.so minimum_uid=100
336 login account required /usr/lib/security/pam_unix_account.so.1
337 login session required /usr/local/lib/security/pam_krb5.so retain_after_close minimum_uid=100
338 login session required /usr/lib/security/pam_unix_session.so.1
339```
340
341A similar configuration could be used for other services, such as ssh.
342See the pam.conf(5) man page for more information. When using this module
343with Solaris login (at least on Solaris 8 and 9), you will probably also
344need to add `retain_after_close` to the PAM configuration to avoid having
345the user's credentials deleted before they are logged in.
346
347The Solaris Kerberos library reportedly does not support prompting for a
348password change of an expired account during authentication. Supporting
349password change for expired accounts on Solaris with native Kerberos may
350therefore require setting the `defer_pwchange` or `force_pwchange` option
351for selected login applications. See the description and warnings about
352that option in the pam_krb5(5) man page.
353
354Some configuration options may be put in the `krb5.conf` file used by your
355Kerberos libraries (usually `/etc/krb5.conf` or
356`/usr/local/etc/krb5.conf`) instead or in addition to the PAM
357configuration. See the man page for more details.
358
359The Kerberos library, via pam-krb5, will prompt the user to change their
360password if their password is expired, but when using OpenSSH, this will
361only work when `ChallengeResponseAuthentication` is enabled. Unless this
362option is enabled, OpenSSH doesn't pass PAM messages to the user and can
363only respond to a simple password prompt.
364
365If you are using MIT Kerberos, be aware that users whose passwords are
366expired will not be prompted to change their password unless the KDC
367configuration for your realm in `[realms]` in `krb5.conf` contains a
368`master_kdc` setting or, if using DNS SRV records, you have a DNS entry
369for `_kerberos-master` as well as `_kerberos`.
370
371## Debugging
372
373The first step when debugging any problems with this module is to add
374`debug` to the PAM options for the module (either in the PAM configuration
375or in `krb5.conf`). This will significantly increase the logging from the
376module and should provide a trace of exactly what failed and any available
377error information.
378
379Many Kerberos authentication problems are due to configuration issues in
380`krb5.conf`. If pam-krb5 doesn't work, first check that `kinit` works on
381the same system. That will test your basic Kerberos configuration. If
382the system has a keytab file installed that's readable by the process
383doing authentication via PAM, make sure that the keytab is current and
384contains a key for `host/<system>` where <system> is the fully-qualified
385hostname. pam-krb5 prevents KDC spoofing by checking the user's
386credentials when possible, but this means that if a keytab is present it
387must be correct or authentication will fail. You can check the keytab
388with `klist -k` and `kinit -k`.
389
390Be sure that all libraries and modules, including PAM modules, loaded by a
391program use the same Kerberos libraries. Sometimes programs that use PAM,
392such as current versions of OpenSSH, also link against Kerberos directly.
393If your sshd is linked against one set of Kerberos libraries and pam-krb5
394is linked against a different set of Kerberos libraries, this will often
395cause problems (such as segmentation faults, bus errors, assertions, or
396other strange behavior). Similar issues apply to the com_err library or
397any other library used by both modules and shared libraries and by the
398application that loads them. If your OS ships Kerberos libraries, it's
399usually best if possible to build all Kerberos software on the system
400against those libraries.
401
402## Implementation Notes
403
404The normal sequence of actions taken for a user login is:
405
406```
407 pam_authenticate
408 pam_setcred(PAM_ESTABLISH_CRED)
409 pam_open_session
410 pam_acct_mgmt
411```
412
413and then at logout:
414
415```
416 pam_close_session
417```
418
419followed by closing the open PAM session. The corresponding `pam_sm_*`
420functions in this module are called when an application calls those public
421interface functions. Not all applications call all of those functions, or
422in particularly that order, although `pam_authenticate` is always first
423and has to be.
424
425When `pam_authenticate` is called, pam-krb5 creates a temporary ticket
426cache in `/tmp` and sets the PAM environment variable `PAM_KRB5CCNAME` to
427point to it. This ticket cache will be automatically destroyed when the
428PAM session is closed and is there only to pass the initial credentials to
429the call to `pam_setcred`. The module would use a memory cache, but
430memory caches will only work if the application preserves the PAM
431environment between the calls to `pam_authenticate` and `pam_setcred`.
432Most do, but OpenSSH notoriously does not and calls `pam_authenticate` in
433a subprocess, so this method is used to pass the tickets to the
434`pam_setcred` call in a different process.
435
436`pam_authenticate` does a complete authentication, including checking the
437resulting TGT by obtaining a service ticket for the local host if
438possible, but this requires read access to the system keytab. If the
439keytab doesn't exist, can't be read, or doesn't include the appropriate
440credentials, the default is to accept the authentication. This can be
441controlled by setting `verify_ap_req_nofail` to true in `[libdefaults]` in
442`/etc/krb5.conf`. `pam_authenticate` also does a basic authorization
443check, by default calling `krb5_kuserok` (which uses `~/.k5login` if
444available and falls back to checking that the principal corresponds to the
445account name). This can be customized with several options documented in
446the pam_krb5(5) man page.
447
448pam-krb5 treats `pam_open_session` and `pam_setcred(PAM_ESTABLISH_CRED)`
449as synonymous, as some applications call one and some call the other.
450Both copy the initial credentials from the temporary cache into a
451permanent cache for this session and set `KRB5CCNAME` in the environment.
452It will remember when the credential cache has been established and then
453avoid doing any duplicate work afterwards, since some applications call
454`pam_setcred` or `pam_open_session` multiple times (most notably X.Org 7
455and earlier xdm, which also throws away the module settings the last time
456it calls them).
457
458`pam_acct_mgmt` finds the ticket cache, reads it in to obtain the
459authenticated principal, and then does is another authorization check
460against `.k5login` or the local account name as described above.
461
462After the call to `pam_setcred` or `pam_open_session`, the ticket cache
463will be destroyed whenever the calling application either destroys the PAM
464environment or calls `pam_close_session`, which it should do on user
465logout.
466
467The normal sequence of events when refreshing a ticket cache (such as
468inside a screensaver) is:
469
470```
471 pam_authenticate
472 pam_setcred(PAM_REINITIALIZE_CRED)
473 pam_acct_mgmt
474```
475
476(`PAM_REFRESH_CRED` may be used instead.) Authentication proceeds as
477above. At the `pam_setcred` stage, rather than creating a new ticket
478cache, the module instead finds the current ticket cache (from the
479`KRB5CCNAME` environment variable or the default ticket cache location
480from the Kerberos library) and then reinitializes it with the credentials
481from the temporary `pam_authenticate` ticket cache. When refreshing a
482ticket cache, the application should not open a session. Calling
483`pam_acct_mgmt` is optional; pam-krb5 doesn't do anything different when
484it's called in this case.
485
486If `pam_authenticate` apparently didn't succeed, or if an account was
487configured to be ignored via `ignore_root` or `minimum_uid`, `pam_setcred`
488(and therefore `pam_open_session`) and `pam_acct_mgmt` return
489`PAM_IGNORE`, which tells the PAM library to proceed as if that module
490wasn't listed in the PAM configuration at all. `pam_authenticate`,
491however, returns failure in the ignored user case by default, since
492otherwise a configuration using `ignore_root` with pam-krb5 as the only
493PAM module would allow anyone to log in as root without a password. There
494doesn't appear to be a case where returning `PAM_IGNORE` instead would
495improve the module's behavior, but if you know of a case, please let me
496know.
497
498By default, `pam_authenticate` intentionally does not follow the PAM
499standard for handling expired accounts and instead returns failure from
500`pam_authenticate` unless the Kerberos libraries are able to change the
501account password during authentication. Too many applications either do
502not call `pam_acct_mgmt` or ignore its exit status. The fully correct PAM
503behavior (returning success from `pam_authenticate` and
504`PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) can be enabled with the
505`defer_pwchange` option.
506
507The `defer_pwchange` option is unfortunately somewhat tricky to implement.
508In this case, the calling sequence is:
509
510```
511 pam_authenticate
512 pam_acct_mgmt
513 pam_chauthtok
514 pam_setcred
515 pam_open_session
516```
517
518During the first `pam_authenticate`, we can't obtain credentials and
519therefore a ticket cache since the password is expired. But
520`pam_authenticate` isn't called again after `pam_chauthtok`, so
521`pam_chauthtok` has to create a ticket cache. We however don't want it to
522do this for the normal password change (`passwd`) case.
523
524What we do is set a flag in our PAM data structure saying that we're
525processing an expired password, and `pam_chauthtok`, if it sees that flag,
526redoes the authentication with password prompting disabled after it
527finishes changing the password.
528
529Unfortunately, when handling password changes this way, `pam_chauthtok`
530will always have to prompt the user for their current password again even
531though they just typed it. This is because the saved authentication
532tokens are cleared after `pam_authenticate` returns, for security reasons.
533We could hack around this by saving the password in our PAM data
534structure, but this would let the application gain access to it (exactly
535what the clearing is intended to prevent) and breaks a PAM library
536guarantee. We could also work around this by having `pam_authenticate`
537get the `kadmin/changepw` authenticator in the expired password case and
538store it for `pam_chauthtok`, but it doesn't seem worth the hassle.
539
540## History and Acknowledgements
541
542Originally written by Frank Cusack <fcusack@fcusack.com>, with the
543following acknowledgement:
544
545> Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King
546> <curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all of
547> whom have written and made available Kerberos 4/5 modules. Although no
548> code in this module is directly from these author's modules, (except the
549> get_user_info() routine in support.c; derived from whichever of these
550> authors originally wrote the first module the other 2 copied from), it
551> was extremely helpful to look over their code which aided in my design.
552
553The module was then patched for the FreeBSD ports collection with
554additional modifications by unknown maintainers and then was modified by
555Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux.
556
557It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian
558and improved and modified by him and later by Russ Allbery to fix bugs and
559add additional features. It was then adopted by Andres Salomon, who added
560support for refreshing credentials.
561
562The current distribution is maintained by Russ Allbery, who also added
563support for reading configuration from `krb5.conf`, added many features
564for compatibility with the Sourceforge module, commented and standardized
565the formatting of the code, and overhauled the documentation.
566
567Thanks to Douglas E. Engert for the initial implementation of PKINIT
568support. I have since modified and reworked it extensively, so any bugs
569or compilation problems are my fault.
570
571Thanks to Markus Moeller for lots of debugging and multiple patches and
572suggestions for improved portability.
573
574Thanks to Booker Bense for the implementation of the `alt_auth_map`
575option.
576
577Thanks to Sam Hartman for the FAST support implementation.
578
579## Support
580
581The [pam-krb5 web page](https://www.eyrie.org/~eagle/software/pam-krb5/)
582will always have the current version of this package, the current
583documentation, and pointers to any additional resources.
584
585For bug tracking, use the [issue tracker on
586GitHub](https://github.com/rra/pam-krb5/issues). However, please be aware
587that I tend to be extremely busy and work projects often take priority.
588I'll save your report and get to it as soon as I can, but it may take me a
589couple of months.
590
591## Source Repository
592
593pam-krb5 is maintained using Git. You can access the current source on
594[GitHub](https://github.com/rra/pam-krb5) or by cloning the repository at:
595
596https://git.eyrie.org/git/kerberos/pam-krb5.git
597
598or [view the repository on the
599web](https://git.eyrie.org/?p=kerberos/pam-krb5.git).
600
601The eyrie.org repository is the canonical one, maintained by the author,
602but using GitHub is probably more convenient for most purposes. Pull
603requests are gratefully reviewed and normally accepted.
604
605## License
606
607The pam-krb5 package as a whole is covered by the following copyright
608statement and license:
609
610> Copyright 2005-2010, 2014-2015, 2017, 2020-2021
611> Russ Allbery <eagle@eyrie.org>
612>
613> Copyright 2009-2011
614> The Board of Trustees of the Leland Stanford Junior University
615>
616> Copyright 2005
617> Andres Salomon <dilinger@debian.org>
618>
619> Copyright 1999-2000
620> Frank Cusack <fcusack@fcusack.com>
621>
622> Redistribution and use in source and binary forms, with or without
623> modification, are permitted provided that the following conditions are
624> met:
625>
626> 1. Redistributions of source code must retain the above copyright
627> notice, and the entire permission notice in its entirety, including
628> the disclaimer of warranties.
629>
630> 2. Redistributions in binary form must reproduce the above copyright
631> notice, this list of conditions and the following disclaimer in the
632> documentation and/or other materials provided with the distribution.
633>
634> 3. The name of the author may not be used to endorse or promote products
635> derived from this software without specific prior written permission.
636>
637> ALTERNATIVELY, this product may be distributed under the terms of the GNU
638> General Public License, in which case the provisions of the GPL are
639> required INSTEAD OF the above restrictions. (This clause is necessary due
640> to a potential bad interaction between the GPL and the restrictions
641> contained in a BSD-style copyright.)
642>
643> THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
644> INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
645> AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
646> THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
647> EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
648> PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
649> PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
650> LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
651> NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
652> SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
653
654Some files in this distribution are individually released under different
655licenses, all of which are compatible with the above general package
656license but which may require preservation of additional notices. All
657required notices, and detailed information about the licensing of each
658file, are recorded in the LICENSE file.
659
660Files covered by a license with an assigned SPDX License Identifier
661include SPDX-License-Identifier tags to enable automated processing of
662license information. See https://spdx.org/licenses/ for more information.
663
664For any copyright range specified by files in this package as YYYY-ZZZZ,
665the range specifies every single year in that closed interval.
666