| 1 |
pam-krb5 4.11 |
| 2 |
(PAM module for Kerberos authentication) |
| 3 |
Maintained by Russ Allbery <[email protected]> |
| 4 |
|
| 5 |
Copyright 2005-2010, 2014-2015, 2017, 2020-2021 Russ Allbery |
| 6 |
<[email protected]>. Copyright 2009-2011 The Board of Trustees of the |
| 7 |
Leland Stanford Junior University. Copyright 2005 Andres Salomon |
| 8 |
<[email protected]>. Copyright 1999-2000 Frank Cusack |
| 9 |
<[email protected]>. This software is distributed under a BSD-style |
| 10 |
license. Please see the section LICENSE below for more information. |
| 11 |
|
| 12 |
BLURB |
| 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 |
|
| 24 |
DESCRIPTION |
| 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 |
|
| 51 |
REQUIREMENTS |
| 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 |
|
| 98 |
BUILDING 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 |
|
| 169 |
TESTING |
| 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 |
|
| 218 |
CONFIGURING |
| 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 |
|
| 344 |
DEBUGGING |
| 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 |
|
| 375 |
IMPLEMENTATION 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 |
|
| 505 |
HISTORY AND ACKNOWLEDGEMENTS |
| 506 |
|
| 507 |
Originally written by Frank Cusack <[email protected]>, with the |
| 508 |
following acknowledgement: |
| 509 |
|
| 510 |
Thanks to Naomaru Itoi <[email protected]>, Curtis King |
| 511 |
<[email protected]>, and Derrick Brashear <[email protected]>, 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 <[email protected]> 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 |
|
| 546 |
SUPPORT |
| 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 |
|
| 563 |
SOURCE 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 |
|
| 582 |
LICENSE |
| 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 <[email protected]> |
| 589 |
Copyright 2009-2011 |
| 590 |
The Board of Trustees of the Leland Stanford Junior University |
| 591 |
Copyright 2005 Andres Salomon <[email protected]> |
| 592 |
Copyright 1999-2000 Frank Cusack <[email protected]> |
| 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. |