pam-krb5 2.6
(PAM module for Kerberos v5 authentication)
Originally written by Frank Cusack
Modifications by Joel Kociolek, Andres Salomon, and Sam Hartman
Maintained by Russ Allbery <rra@stanford.edu>
See the COPYRIGHT file, included in this distribution, for copyright and
redistribution information. See the HISTORY section below for the
e-mail addresses of contributors and thanks to those who have provided
help.
BLURB
pam-krb5 is a Kerberos v5 PAM module for either MIT Kerberos or Heimdal.
It supports ticket refreshing by screen savers, configurable
authorization handling, authentication of non-local accounts for network
services, password changing, and password expiration, as well as all the
standard expected PAM features. It works correctly with OpenSSH, even
with ChallengeResponseAuthentication and PrivilegeSeparation enabled,
and supports configuration either by PAM options or in krb5.conf or
both.
DESCRIPTION
pam-krb5 provides a Kerberos v5 PAM module that supports authentication,
user ticket cache handling, simple authorization (via .k5login or
checking Kerberos principals against local usernames), and password
changing. It can be configured through either options in the PAM
configuration itself or through entries in the system krb5.conf file,
and it tries to work around PAM implementation flaws in commonly-used
PAM-enabled applications such as OpenSSH and xdm.
This is not the Kerberos v5 PAM module maintained on Sourceforge and
used on Red Hat systems. It is an independent implementation that, if
it ever shared any common code, diverged long ago. It supports some
features that the Sourceforge module does not (particularly around
authorization), and does not support some options (particularly ones not
directly related to Kerberos v5) that it does. This module will never
support Kerberos v4 and will probably never directly support AFS (AFS is
probably better-supported via a dedicated AFS PAM module that can be
stacked with the Kerberos module of your choice).
Either MIT Kerberos or Heimdal are supported. The Makefile will require
some modifications to build with Heimdal. The MIT Kerberos support is
better tested. MIT Keberos 1.3 or later may be required; this module
has not been tested with earlier versions.
This module should work on Linux and Solaris (and build with either gcc
or the Sun C compiler), but has been far more heavily tested on Linux.
Other PAM implementations will probably require some porting, and the
module requires gcc to even attempt to build on platforms other than
Solaris.
COMPILING AND INSTALLING
To build the module with MIT Kerberos on a Linux system, just run:
./configure
make
On Solaris, expect many warnings about type mismatches. These warnings
should be harmless. Linux and Solaris differ in which struct members
and function parameters are declared const and there is no simple way to
write code that compiles without warnings on both platforms.
To install the module into /usr/local/lib/security and the man page into
/usr/local/share/man/man5, run:
make install
You can change the installation locations with the --prefix, --mandir,
and --libdir options to configure. The module will be installed in a
subdirectory of $libdir named security. Alternately, you can simply
copy pam_krb5.so to whatever directory you use for PAM modules. On
Solaris, you will need to make the module executable.
If your Kerberos libraries aren't installed in a location found by your
compiler by default, use the --with-kerberos=PATH option to configure.
The Kerberos libraries will then be expected in PATH/lib and the headers
in PATH/include.
To specify a particular krb5-config script to use, either set the
KRB5_CONFIG environment variable or pass it to configure like:
./configure KRB5_CONFIG=/path/to/krb5-config
You can pass the --enable-reduced-depends flag to configure to try to
minimize the shared library dependencies encoded in the binaries. This
omits from the link line all the libraries included solely because the
Kerberos libraries depend on them and instead links the programs only
against libraries whose APIs are called directly. This will only work
with shared Kerberos libraries and will only work on platforms where
shared libraries properly encode their own dependencies (such as Linux).
It is intended primarily for building packages for Linux distributions
to avoid encoding unnecessary shared library dependencies that make
shared library migrations more difficult. If none of the above made any
sense to you, don't bother with this flag.
CONFIGURING
Just installing the module does not enable it or change anything about
your system authentication configuration. To use the module for all
system authentication on Debian systems, put something like:
auth sufficient pam_krb5.so minimum_uid=1000
auth required pam_unix.so try_first_pass nullok_secure
in /etc/pam.d/common-auth, something like:
session optional pam_krb5.so minimum_uid=1000
session required pam_unix.so
in /etc/pam.d/common-session, and something like:
account required pam_krb5.so minimum_uid=1000
account required pam_unix.so
in /etc/pam.d/common-account. The minimum_uid setting tells the PAM
module to pass on any users with a UID lower than 1000, thereby
bypassing Kerberos v5 authentication for the root account and any system
accounts. You normally want to do this since otherwise, if the network
is down, the Kerberos authentication can time out and make it difficult
to log in as root and fix matters. This also avoids problems with
Kerberos principals that happen to match system accounts accidentally
getting access to those accounts.
If your users should normally all use Kerberos passwords exclusively,
putting something like:
password sufficient pam_krb5.so minimum_uid=1000
password required pam_unix.so nullok obscure min=4 max=8 md5
in /etc/pam.d/common-password will change users' passwords in Kerberos
by default and then only fall back on Unix if that doesn't work. (You
can make this tighter by using the more complex new-style PAM
configuration.) If you instead want to synchronize local and Kerberos
passwords and change them both at the same time, you can do something
like:
password required pam_unix.so nullok obscure min=4 max=8 md5
password required pam_krb5.so use_authtok minimum_uid=1000
There are many, many other possibilities. See the Linux PAM
documentation for all the configuration options.
On Red Hat systems, modify /etc/pam.d/system-auth instead, which
contains all of the configuration for the different stacks.
You can also use pam-krb5 only for specific services. In that case,
modify the files in /etc/pam.d for that particular service to use
pam_krb5.so for authentication. For services that are using passwords
over TLS to authenticate users, you may want to use the ignore_k5login
and no_ccache options to the authenticate module; .k5login authorization
is only meaningful for local accounts and ticket caches are usually
(although not always) only useful for interactive sessions.
Configuring the module for Solaris is both simpler and less flexible,
since Solaris (at least Solaris 8 and 9) use a single /etc/pam.conf file
that contains configuration for all programs. See the pam.conf man page
for more information. When using this module with Solaris login (at
least on Solaris 8 and 9), you will probably also need to add
retain_after_close to the PAM configuration to avoid having the user's
credentials deleted before they are logged in.
IMPLEMENTATION NOTES
The normal sequence of actions taken for a user login is:
pam_authenticate
pam_setcred(PAM_ESTABLISH_CRED)
pam_open_session
pam_acct_mgmt
and then at logout:
pam_close_session
followed by closing the open PAM session. The corresponding pam_sm_*
functions in this module are called when an application calls those
public interface functions. Not all applications call all of those
functions, or in particularly that order, although pam_authenticate is
always first and has to be.
When pam_authenticate is called, pam-krb5 creates a temporary ticket
cache in /tmp and sets the PAM environment variable PAM_KRB5CCNAME to
point to it. This ticket cache will be automatically destroyed when the
PAM session is closed and is there only to pass the initial credentials
to the call to pam_setcred. The module would use a memory cache, but
memory caches will only work if the application preserves the PAM
environment between the calls to pam_authenticate and pam_setcred. Most
do, but OpenSSH notoriously does not and calls pam_authenticate in a
subprocess, so this method is used to pass the tickets to the
pam_setcred call in a different process.
pam_authenticate does a complete authentication, including checking the
resulting TGT by obtaining a service ticket for the local host if
possible, but this requires read access to the system keytab. If the
keytab doesn't exist, can't be read, or doesn't include the appropriate
credentials, the default is to accept the authentication. This can be
controlled by setting verify_ap_req_nofail to true in [libdefaults] in
/etc/krb5.conf. pam_authenticate also does a basic authorization check,
by default calling krb5_kuserok (which uses ~/.k5login if available and
falls back to checking that the principal corresponds to the account
name). This can be customized with several options documented in the
pam_krb5(8) man page.
pam-krb5 treats pam_open_session and pam_setcred(PAM_ESTABLISH_CRED) as
synonymous, as some applications call one and some call the other.
Either copy the initial credentials from the temporary cache into a
permanent cache for this session and set KRB5CCNAME in the environment.
It will remember when the credential cache has been established and then
avoid doing any duplicate work afterwards, since some applications call
pam_setcred or pam_open_session multiple times (most notably X.Org 7 and
earlier xdm, which also throws away the module settings the last time it
calls them).
All pam_acct_mgmt does is another simple authorization check.
After the call to pam_setcred or pam_open_session, the ticket cache will
be destroyed whenever the calling application either destroys the PAM
environment or calls pam_close_session, which it should do on user
logout.
The normal sequence of events when refreshing a ticket cache (such as
inside a screensaver) is:
pam_authenticate
pam_setcred(PAM_REFRESH_CRED)
pam_acct_mgmt
Authentication proceeds as above. At the pam_setcred stage, rather than
creating a new ticket cache, the module instead finds the current ticket
cache (from the KRB5CCNAME environment variable or the default ticket
cache location from the Kerberos library) and then reinitializes it with
the credentials from the temporary pam_authenticate ticket cache. When
refreshing a ticket cache, the application should *not* open a session.
Calling pam_acct_mgmt is optional; pam-krb5 doesn't do anything
different when it's called in this case.
HISTORY AND ACKNOWLEDGEMENTS
Originally written by Frank Cusack <fcusack@fcusack.com>, with the
following acknowledgement:
Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King
<curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all
of whom have written and made available Kerberos 4/5 modules.
Although no code in this module is directly from these author's
modules, (except the get_user_info() routine in support.c; derived
from whichever of these authors originally wrote the first module the
other 2 copied from), it was extremely helpful to look over their code
which aided in my design.
The module was then patched for the FreeBSD ports collection with
additional modifications by unknown maintainers and then was modified by
Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux.
It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian
and improved and modified by him and later by Russ Allbery to fix bugs
and add additional features. It was then adopted by Andres Salomon, who
added support for refreshing credentials.
The current distribution is maintained by Russ Allbery, who also added
support for reading configuration from krb5.conf, added many features
for compatibility with the Sourceforge module, commented and
standardized the formatting of the code, and overhauled the
documentation.