1# Package metadata for pam-krb5. 2# 3# This file contains configuration for DocKnot used to generate 4# documentation files (like README.md) and web pages. Other documentation 5# in this package is generated automatically from these files as part of 6# the release process. For more information, see DocKnot's documentation. 7# 8# DocKnot is available from <https://www.eyrie.org/~eagle/software/docknot/>. 9# 10# Copyright 2017, 2020-2021 Russ Allbery <eagle@eyrie.org> 11# 12# SPDX-License-Identifier: BSD-3-clause or GPL-1+ 13 14format: v1 15 16name: pam-krb5 17maintainer: Russ Allbery <eagle@eyrie.org> 18version: '4.11' 19synopsis: PAM module for Kerberos authentication 20 21license: 22 name: BSD-3-clause-or-GPL-1+ 23copyrights: 24 - holder: Russ Allbery <eagle@eyrie.org> 25 years: 2005-2010, 2014-2015, 2017, 2020-2021 26 - holder: The Board of Trustees of the Leland Stanford Junior University 27 years: 2009-2011 28 - holder: Andres Salomon <dilinger@debian.org> 29 years: '2005' 30 - holder: Frank Cusack <fcusack@fcusack.com> 31 years: 1999-2000 32 33build: 34 autoconf: '2.64' 35 automake: '1.11' 36 autotools: true 37 kerberos: true 38 manpages: true 39 middle: | 40 The module will be installed in `/usr/local/lib/security` by default, but 41 expect to have to override this using `--libdir`. The correct 42 installation path for PAM modules varies considerably between systems. 43 The module will always be installed in a subdirectory named `security` 44 under the specified value of `--libdir`. On Red Hat Linux, for example, 45 `--libdir=/usr/lib64` is appropriate to install the module into the system 46 PAM directory. On Debian's amd64 architecture, 47 `--libdir=/usr/lib/x86_64-linux-gnu` would be correct. 48 reduced_depends: true 49 type: Autoconf 50 valgrind: true 51distribution: 52 packaging: 53 debian: 54 package: libpam-krb5 55 summary: | 56 Debian packages are available from Debian in Debian 4.0 (etch) and 57 later releases as libpam-krb5 and libpam-heimdal. The former packages 58 are built against the MIT Kerberos libraries and the latter against 59 the Heimdal libraries. 60 section: kerberos 61 tarname: pam-krb5 62 version: pam-krb5 63support: 64 email: eagle@eyrie.org 65 github: rra/pam-krb5 66 web: https://www.eyrie.org/~eagle/software/pam-krb5/ 67vcs: 68 browse: https://git.eyrie.org/?p=kerberos/pam-krb5.git 69 github: rra/pam-krb5 70 openhub: https://www.openhub.net/p/pamkrb5 71 status: 72 workflow: build 73 type: Git 74 url: https://git.eyrie.org/git/kerberos/pam-krb5.git 75 76quote: 77 author: Joyce McGreevy 78 date: 2003-11-17 79 text: | 80 "You're always going to have some people who can't appreciate the thrill 81 of a tepid change for the somewhat better," explained one source. 82 title: '"Look, ma, no hands!"' 83 work: Salon 84advisories: 85 - date: 2020-03-30 86 threshold: '4.9' 87 versions: 4.8 and earlier 88 - date: 2009-02-11 89 threshold: '3.13' 90 versions: 3.12 and earlier 91docs: 92 user: 93 - name: pam-krb5 94 title: Manual page 95 96blurb: | 97 pam-krb5 is a Kerberos PAM module for either MIT Kerberos or Heimdal. It 98 supports ticket refreshing by screen savers, configurable authorization 99 handling, authentication of non-local accounts for network services, 100 password changing, and password expiration, as well as all the standard 101 expected PAM features. It works correctly with OpenSSH, even with 102 ChallengeResponseAuthentication and PrivilegeSeparation enabled, and 103 supports extensive configuration either by PAM options or in krb5.conf or 104 both. PKINIT is supported with recent versions of both MIT Kerberos and 105 Heimdal and FAST is supported with recent MIT Kerberos. 106 107description: | 108 pam-krb5 provides a Kerberos PAM module that supports authentication, user 109 ticket cache handling, simple authorization (via .k5login or checking 110 Kerberos principals against local usernames), and password changing. It can 111 be configured through either options in the PAM configuration itself or 112 through entries in the system krb5.conf file, and it tries to work around 113 PAM implementation flaws in commonly-used PAM-enabled applications such as 114 OpenSSH and xdm. It supports both PKINIT and FAST to the extent that the 115 underlying Kerberos libraries support these features. 116 117 This is not the Kerberos PAM module maintained on Sourceforge and used on 118 Red Hat systems. It is an independent implementation that, if it ever 119 shared any common code, diverged long ago. It supports some features that 120 the Sourceforge module does not (particularly around authorization), and 121 does not support some options (particularly ones not directly related to 122 Kerberos) that it does. This module will never support Kerberos v4 or AFS. 123 For an AFS session module that works with this module (or any other Kerberos 124 PAM module), see 125 [pam-afs-session](https://www.eyrie.org/~eagle/software/pam-afs-session/). 126 127 If there are other options besides AFS and Kerberos v4 support from the 128 Sourceforge PAM module that you're missing in this module, please let me 129 know. 130 131requirements: | 132 Either MIT Kerberos (or Kerberos implementations based on it) or Heimdal are 133 supported. MIT Keberos 1.3 or later may be required; this module has not 134 been tested with earlier versions. 135 136 For PKINIT support, Heimdal 0.8rc1 or later or MIT Kerberos 1.6.3 or later 137 are required. Earlier MIT Kerberos 1.6 releases have a bug in their 138 handling of PKINIT options. MIT Kerberos 1.12 or later is required to use 139 the use_pkinit PAM option. 140 141 For FAST (Flexible Authentication Secure Tunneling) support, MIT Kerberos 142 1.7 or higher is required. For anonymous FAST support, anonymous 143 authentication (generally anonymous PKINIT) support is required in both the 144 Kerberos libraries and in the local KDC. 145 146 This module should work on Linux and build with gcc or clang. It may still 147 work on Solaris and build with the Sun C compiler, but I have only tested it 148 on Linux recently. There is beta-quality support for the AIX NAS Kerberos 149 implementation that has not been tested in years. Other PAM implementations 150 will probably require some porting, although untested build system support 151 is present for FreeBSD, Mac OS X, and HP-UX. I personally can only test on 152 Linux and rely on others to report problems on other operating systems. 153 154 Old versions of OpenSSH are known to call `pam_authenticate` followed by 155 `pam_setcred(PAM_REINITIALIZE_CRED)` without first calling 156 `pam_open_session`, thereby requesting that an existing ticket cache be 157 renewed (similar to what a screensaver would want) rather than requesting a 158 new ticket cache be created. Since this behavior is indistinguishable at 159 the PAM level from a screensaver, pam-krb5 when used with these old versions 160 of OpenSSH will refresh the ticket cache of the OpenSSH daemon rather than 161 setting up a new ticket cache for the user. The resulting ticket cache will 162 have the correct permissions (this is not a security concern), but will not 163 be named correctly or referenced in the user's environment and will be 164 overwritten by the next user login. The best solution to this problem is to 165 upgrade OpenSSH. I'm not sure exactly when this problem was fixed, but at 166 the very least OpenSSH 4.3 and later do not exhibit it. 167 168test: 169 lancaster: true 170 prefix: | 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 suffix: | 182 The default libkadm5clnt library on the system must match the 183 implementation of your KDC for the module/expired test to work, since the 184 two kadmin protocols are not compatible. If you use the MIT library 185 against a Heimdal server, the test will be skipped; if you use the Heimdal 186 library against an MIT server, the test suite may hang. 187 188 Several `module/expired` tests are expected to fail with Heimdal 1.5 due 189 to a bug in Heimdal with reauthenticating immediately after a 190 library-mediated password change of an expired password. This is fixed in 191 later releases of Heimdal. 192 193 To run the full test suite, Perl 5.10 or later is required. The following 194 additional Perl modules will be used if present: 195 196 * Test::Pod 197 * Test::Spelling 198 199 All are available on CPAN. Those tests will be skipped if the modules are 200 not available. 201 202sections: 203 - title: Configuring 204 body: | 205 Just installing the module does not enable it or change anything about 206 your system authentication configuration. To use the module for all 207 system authentication on Debian systems, put something like: 208 209 ``` 210 auth sufficient pam_krb5.so minimum_uid=1000 211 auth required pam_unix.so try_first_pass nullok_secure 212 ``` 213 214 in `/etc/pam.d/common-auth`, something like: 215 216 ``` 217 session optional pam_krb5.so minimum_uid=1000 218 session required pam_unix.so 219 ``` 220 221 in `/etc/pam.d/common-session`, and something like: 222 223 ``` 224 account required pam_krb5.so minimum_uid=1000 225 account required pam_unix.so 226 ``` 227 228 in `/etc/pam.d/common-account`. The `minimum_uid` setting tells the PAM 229 module to pass on any users with a UID lower than 1000, thereby 230 bypassing Kerberos authentication for the root account and any system 231 accounts. You normally want to do this since otherwise, if the network 232 is down, the Kerberos authentication can time out and make it difficult 233 to log in as root and fix matters. This also avoids problems with 234 Kerberos principals that happen to match system accounts accidentally 235 getting access to those accounts. 236 237 Be sure to include the module in the session group as well as the auth 238 group. Without the session entry, the user's ticket cache will not be 239 created properly for ssh logins (among possibly others). 240 241 If your users should normally all use Kerberos passwords exclusively, 242 putting something like: 243 244 ``` 245 password sufficient pam_krb5.so minimum_uid=1000 246 password required pam_unix.so try_first_pass obscure md5 247 ``` 248 249 in `/etc/pam.d/common-password` will change users' passwords in Kerberos 250 by default and then only fall back on Unix if that doesn't work. (You 251 can make this tighter by using the more complex new-style PAM 252 configuration.) If you instead want to synchronize local and Kerberos 253 passwords and change them both at the same time, you can do something 254 like: 255 256 ``` 257 password required pam_unix.so obscure sha512 258 password required pam_krb5.so use_authtok minimum_uid=1000 259 ``` 260 261 If you have multiple environments that you want to synchronize and you 262 don't want password changes to continue if the Kerberos password change 263 fails, use the `clear_on_fail` option. For example: 264 265 ``` 266 password required pam_krb5.so clear_on_fail minimum_uid=1000 267 password required pam_unix.so use_authtok obscure sha512 268 password required pam_smbpass.so use_authtok 269 ``` 270 271 In this case, if `pam_krb5` cannot change the password (due to password 272 strength rules on the KDC, for example), it will clear the stored 273 password (because of the `clear_on_fail` option), and since `pam_unix` 274 and `pam_smbpass` are both configured with `use_authtok`, they will both 275 fail. `clear_on_fail` is not the default because it would interfere 276 with the more common pattern of falling back to local passwords if the 277 user doesn't exist in Kerberos. 278 279 If you use a more complex configuration with the Linux PAM `[]` syntax 280 for the session and account groups, note that `pam_krb5` returns a 281 status of ignore, not success, if the user didn't log on with Kerberos. 282 You may need to handle that explicitly with `ignore=ignore` in your 283 action list. 284 285 There are many, many other possibilities. See the Linux PAM 286 documentation for all the configuration options. 287 288 On Red Hat systems, modify `/etc/pam.d/system-auth` instead, which 289 contains all of the configuration for the different stacks. 290 291 You can also use pam-krb5 only for specific services. In that case, 292 modify the files in `/etc/pam.d` for that particular service to use 293 `pam_krb5.so` for authentication. For services that are using passwords 294 over TLS to authenticate users, you may want to use the `ignore_k5login` 295 and `no_ccache` options to the authenticate module. `.k5login` 296 authorization is only meaningful for local accounts and ticket caches 297 are usually (although not always) only useful for interactive sessions. 298 299 Configuring the module for Solaris is both simpler and less flexible, 300 since Solaris (at least Solaris 8 and 9, which are the last versions of 301 Solaris with which this module was extensively tested) use a single 302 `/etc/pam.conf` file that contains configuration for all programs. For 303 console login on Solaris, try something like: 304 305 ``` 306 login auth sufficient /usr/local/lib/security/pam_krb5.so minimum_uid=100 307 login auth required /usr/lib/security/pam_unix_auth.so.1 use_first_pass 308 login account required /usr/local/lib/security/pam_krb5.so minimum_uid=100 309 login account required /usr/lib/security/pam_unix_account.so.1 310 login session required /usr/local/lib/security/pam_krb5.so retain_after_close minimum_uid=100 311 login session required /usr/lib/security/pam_unix_session.so.1 312 ``` 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 318 to avoid having the user's credentials deleted before they are logged 319 in. 320 321 The Solaris Kerberos library reportedly does not support prompting for a 322 password change of an expired account during authentication. Supporting 323 password change for expired accounts on Solaris with native Kerberos may 324 therefore require setting the `defer_pwchange` or `force_pwchange` 325 option for selected login applications. See the description and 326 warnings about that option in the pam_krb5(5) man page. 327 328 Some configuration options may be put in the `krb5.conf` file used by 329 your Kerberos libraries (usually `/etc/krb5.conf` or 330 `/usr/local/etc/krb5.conf`) instead or in addition to the PAM 331 configuration. See the man page for more details. 332 333 The Kerberos library, via pam-krb5, will prompt the user to change their 334 password if their password is expired, but when using OpenSSH, this will 335 only work when `ChallengeResponseAuthentication` is enabled. Unless 336 this option is enabled, OpenSSH doesn't pass PAM messages to the user 337 and can only respond to a simple password prompt. 338 339 If you are using MIT Kerberos, be aware that users whose passwords are 340 expired will not be prompted to change their password unless the KDC 341 configuration for your realm in `[realms]` in `krb5.conf` contains a 342 `master_kdc` setting or, if using DNS SRV records, you have a DNS entry 343 for `_kerberos-master` as well as `_kerberos`. 344 - title: Debugging 345 body: | 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 348 configuration or in `krb5.conf`). This will significantly increase the 349 logging from the module and should provide a trace of exactly what 350 failed and any 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 354 on the same system. That will test your basic Kerberos configuration. 355 If 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 - title: Implementation Notes 375 body: | 376 The normal sequence of actions taken for a user login is: 377 378 ``` 379 pam_authenticate 380 pam_setcred(PAM_ESTABLISH_CRED) 381 pam_open_session 382 pam_acct_mgmt 383 ``` 384 385 and then at logout: 386 387 ``` 388 pam_close_session 389 ``` 390 391 followed by closing the open PAM session. The corresponding `pam_sm_*` 392 functions in this module are called when an application calls those 393 public interface functions. Not all applications call all of those 394 functions, or in particularly that order, although `pam_authenticate` is 395 always first and has to be. 396 397 When `pam_authenticate` is called, pam-krb5 creates a temporary ticket 398 cache in `/tmp` and sets the PAM environment variable `PAM_KRB5CCNAME` 399 to point to it. This ticket cache will be automatically destroyed when 400 the PAM session is closed and is there only to pass the initial 401 credentials to the call to `pam_setcred`. The module would use a memory 402 cache, but memory caches will only work if the application preserves the 403 PAM environment between the calls to `pam_authenticate` and 404 `pam_setcred`. Most do, but OpenSSH notoriously does not and calls 405 `pam_authenticate` in a subprocess, so this method is used to pass the 406 tickets to the `pam_setcred` call in a different process. 407 408 `pam_authenticate` does a complete authentication, including checking 409 the resulting TGT by obtaining a service ticket for the local host if 410 possible, but this requires read access to the system keytab. If the 411 keytab doesn't exist, can't be read, or doesn't include the appropriate 412 credentials, the default is to accept the authentication. This can be 413 controlled by setting `verify_ap_req_nofail` to true in `[libdefaults]` 414 in `/etc/krb5.conf`. `pam_authenticate` also does a basic authorization 415 check, by default calling `krb5_kuserok` (which uses `~/.k5login` if 416 available and falls back to checking that the principal corresponds to 417 the account name). This can be customized with several options 418 documented in the pam_krb5(5) man page. 419 420 pam-krb5 treats `pam_open_session` and `pam_setcred(PAM_ESTABLISH_CRED)` 421 as synonymous, as some applications call one and some call the other. 422 Both copy the initial credentials from the temporary cache into a 423 permanent cache for this session and set `KRB5CCNAME` in the 424 environment. It will remember when the credential cache has been 425 established and then avoid doing any duplicate work afterwards, since 426 some applications call `pam_setcred` or `pam_open_session` multiple 427 times (most notably X.Org 7 and earlier xdm, which also throws away the 428 module settings the last time it calls them). 429 430 `pam_acct_mgmt` finds the ticket cache, reads it in to obtain the 431 authenticated principal, and then does is another authorization check 432 against `.k5login` or the local account name as described above. 433 434 After the call to `pam_setcred` or `pam_open_session`, the ticket cache 435 will be destroyed whenever the calling application either destroys the 436 PAM environment or calls `pam_close_session`, which it should do on user 437 logout. 438 439 The normal sequence of events when refreshing a ticket cache (such as 440 inside a screensaver) is: 441 442 ``` 443 pam_authenticate 444 pam_setcred(PAM_REINITIALIZE_CRED) 445 pam_acct_mgmt 446 ``` 447 448 (`PAM_REFRESH_CRED` may be used instead.) Authentication proceeds as 449 above. At the `pam_setcred` stage, rather than creating a new ticket 450 cache, the module instead finds the current ticket cache (from the 451 `KRB5CCNAME` environment variable or the default ticket cache location 452 from the Kerberos library) and then reinitializes it with the 453 credentials from the temporary `pam_authenticate` ticket cache. When 454 refreshing a ticket cache, the application should not open a session. 455 Calling `pam_acct_mgmt` is optional; pam-krb5 doesn't do anything 456 different when it's called in this case. 457 458 If `pam_authenticate` apparently didn't succeed, or if an account was 459 configured to be ignored via `ignore_root` or `minimum_uid`, 460 `pam_setcred` (and therefore `pam_open_session`) and `pam_acct_mgmt` 461 return `PAM_IGNORE`, which tells the PAM library to proceed as if that 462 module wasn't listed in the PAM configuration at all. 463 `pam_authenticate`, however, returns failure in the ignored user case by 464 default, since otherwise a configuration using `ignore_root` with 465 pam-krb5 as the only PAM module would allow anyone to log in as root 466 without a password. There doesn't appear to be a case where returning 467 `PAM_IGNORE` instead would improve the module's behavior, but if you 468 know of a case, please let me know. 469 470 By default, `pam_authenticate` intentionally does not follow the PAM 471 standard for handling expired accounts and instead returns failure from 472 `pam_authenticate` unless the Kerberos libraries are able to change the 473 account password during authentication. Too many applications either do 474 not call `pam_acct_mgmt` or ignore its exit status. The fully correct 475 PAM behavior (returning success from `pam_authenticate` and 476 `PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) can be enabled with the 477 `defer_pwchange` option. 478 479 The `defer_pwchange` option is unfortunately somewhat tricky to 480 implement. In this case, the calling sequence is: 481 482 ``` 483 pam_authenticate 484 pam_acct_mgmt 485 pam_chauthtok 486 pam_setcred 487 pam_open_session 488 ``` 489 490 During the first `pam_authenticate`, we can't obtain credentials and 491 therefore a ticket cache since the password is expired. But 492 `pam_authenticate` isn't called again after `pam_chauthtok`, so 493 `pam_chauthtok` has to create a ticket cache. We however don't want it 494 to do this for the normal password change (`passwd`) case. 495 496 What we do is set a flag in our PAM data structure saying that we're 497 processing an expired password, and `pam_chauthtok`, if it sees that 498 flag, redoes the authentication with password prompting disabled after 499 it finishes changing the password. 500 501 Unfortunately, when handling password changes this way, `pam_chauthtok` 502 will always have to prompt the user for their current password again 503 even though they just typed it. This is because the saved 504 authentication tokens are cleared after `pam_authenticate` returns, for 505 security reasons. We could hack around this by saving the password in 506 our PAM data structure, but this would let the application gain access 507 to it (exactly what the clearing is intended to prevent) and breaks a 508 PAM library guarantee. We could also work around this by having 509 `pam_authenticate` get the `kadmin/changepw` authenticator in the 510 expired password case and store it for `pam_chauthtok`, but it doesn't 511 seem worth the hassle. 512 - title: History and Acknowledgements 513 body: | 514 Originally written by Frank Cusack <fcusack@fcusack.com>, with the 515 following acknowledgement: 516 517 > Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King 518 > <curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all 519 > of whom have written and made available Kerberos 4/5 modules. 520 > Although no code in this module is directly from these author's 521 > modules, (except the get_user_info() routine in support.c; derived 522 > from whichever of these authors originally wrote the first module the 523 > other 2 copied from), it was extremely helpful to look over their code 524 > which aided in my design. 525 526 The module was then patched for the FreeBSD ports collection with 527 additional modifications by unknown maintainers and then was modified by 528 Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux. 529 530 It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian 531 and improved and modified by him and later by Russ Allbery to fix bugs 532 and add additional features. It was then adopted by Andres Salomon, who 533 added support for refreshing credentials. 534 535 The current distribution is maintained by Russ Allbery, who also added 536 support for reading configuration from `krb5.conf`, added many features 537 for compatibility with the Sourceforge module, commented and 538 standardized the formatting of the code, and overhauled the 539 documentation. 540 541 Thanks to Douglas E. Engert for the initial implementation of PKINIT 542 support. I have since modified and reworked it extensively, so any bugs 543 or compilation problems are my fault. 544 545 Thanks to Markus Moeller for lots of debugging and multiple patches and 546 suggestions for improved portability. 547 548 Thanks to Booker Bense for the implementation of the `alt_auth_map` 549 option. 550 551 Thanks to Sam Hartman for the FAST support implementation. 552