This module for Linux-PAM implements Kerberos 5 password-checking with
optional Kerberos 4 compatible ticket files and and aklog-style AFS
token-grabbing.  The pam_krb5 module is always built, and when compiled
on a system with libkrbafs installed, pam_krb5afs.so will also be built.

It implements authentication, account management, session management,
and password-changing functions.  Sample configuration files for many
services are included.

The pam_sm_authenticate() function checks the user name and password in
the user's realm.  It takes the standard parameters required by the PAM
documentation, as well as a few others listed below.

With no arguments, the pam_sm_authenticate() function defaults to
"try_first_pass" mode.  The TGT obtained and is saved for later use by
the pam_sm_setcred() function, but the TGT is NOT stored on disk.  The
new TGT is validated using a copy of the key for the local workstation's
host service if it is found in the local keytab file.

The pam_sm_setcred() function creates a Kerberos 5 ticket file and, if
libkrb524 was found at compile-time, can obtain and create a Kerberos 4
ticket file using the krb524 service running on the KDC.  If libkrbafs
was found at compile-time, the krb5afs module will also create a PAG
and get tokens for AFS cells specified in the configuration file.

The account management function (pam_sm_acct_mgmt()) checks the principal
which was authenticated against the PAM_USER's .k5login file, and checks
that the principal's key has not expired.  If the key has expired, it
returns a proper error code to libpam which should allow an application to
then call pam_chauthtok() to change the user's password.

The session management functions (pam_sm_open_session() and
pam_sm_close_session()) merely wrap calls to pam_setcred with the
PAM_ESTABLISH_CREDS and PAM_DELETE_CREDS flags, respectively, which is
handy because on my test box some things just don't work right.

Because session-specific ticket files require that the KRBTKFILE and
KRB5CCNAME environment variables are set correctly, certain programs that
create their own environments but don't incorporate the results of
pam_getenvlist() will work, but a user running 'klist' will think that
she has no tickets.  The number of cases where this happens should
decrease with time.

Certain settings for the module are now stored in the krb5.conf file, which
is usually stored in /etc.  The section name is "appdefaults", and the
subsection name is "pam":

[appdefaults]
  pam = {
    debug = true
    ticket_lifetime = 36000
    renew_lifetime = 36000
    forwardable = true
    krb4_convert = true
    afs_cells = eos.example.edu unity.example.edu bp.example.edu
    hosts = thermo.stat.example.edu alf.physics.example.edu
    max_timeout = 30
    timeout_shift = 2
    initial_timeout = 1
  }

Note that previous versions of pam_krb5 used the "pam" section instead of
a subsection of the "appdefaults" section.  This is still supported if
you use the --enable-confparser option at compile time, but not encouraged.
Mixing the two is sure to be confusing.

Descriptions of the configuration file directives read by both modules:
   debug		Gratuitous debugging info via syslog.
   ticket_lifetime	How long tickets are good, in seconds.  The default
  			is 36000 (= 10 hours).
   renew_lifetime	How long tickets are renewable, in seconds.  The
   			default is also 36000 (10 hours).
   forwardable		Whether or not tickets are forwardable.  Default = true.
   krb4_convert		Get krb4 tickets by talking to krb524d on the KDC.
   native_krb4_tgt	Get krb4 tickets by talking native krb4
			to a krb4 capable KDC.
   afs_cells		Cells to get tokens in.  Requires that krb4_convert be
			set.  Default as distributed is "eos unity bp".  Note
			that this is only supported by the pam_krb5afs module.
   hosts		Hosts this ticket will also be good for, in addition to
			this one.  Primarily for use behind firewalls.
   ccache_dir		The directory to store ccache files in.  The default is
			to use /tmp, but some people prefer /var/tmp.
   banner		What the module should announce itself as when changing
			passwords.  Defaults to "Kerberos 5".
   keytab		The name of a keytab file to use for TGT validation.
			The default is "/etc/krb5.keytab".
   required_tgs		The name of a service principal (with its key in the
			given keytab file) which is to be used to validate TGTs.
			The default is "host/<hostname>".
   max_timeout		The maximum amount of time to wait for a response
                        from the KDCs, in seconds (mit-krb5 specific)
   timeout_shift        The amount to increase the timeout (by left
                        shifting) by after each failed request
			(mit-krb5 specific)
   initial_timeout      The time to wait for the first KDC to respond, in
                        seconds (mit-krb5 specific)
   heimdal_kdc_timout	Maximum time to wait for a reply from the kdc,
			default is 3 seconds. (heimdal specific)
   addressless          Whether tickets can be used from any address -
                        useful from behind NATs, or on dialups where IP
                        address changes regularly.  Conflicts with the
			hosts option (above).
   retain_after_close	Retain the credentials and tokens after session closed.
   old_password_from_auth
			Support broken programs at password change
			(e.g few Solaris passwd, few poppasswd etc)
			which first run the auth chain, then think that
			chauthok should only require the new passwd for
			passwd change. And also these programs save the
			old passwd (from auth chain) to the new passwd.

Descriptions of configuration directives for use in /etc/pam.d:
   use_first_pass	Use password obtained by a previous module.
   try_first_pass	Same as above, but prompt for another one to try the
			one used by the other module fails.
   skip_first_pass	Skip trying previously-entered password altogether.
   debug		Switch on debugging via syslog.
   tokens		Get tokens during authentication.  Needed for wu-ftpd,
			Samba, and some other programs that don't use sessions
			and don't call pam_setcred, but need tokens.  Note
                        that this is only supported by the pam_krb5afs module.
   creds		Same as the tokens options, but it get/keep the
			kerberos credentials too.
   refresh_creds or
   refresh_tokens	It try to refresh the existent credentials and tokens.
			If it can't refresh a cred (maybe because the user's
			principal and the ticket's principal are different) then
			it will dont save the the cred which was acquired
			during authentication unless you use the
			retain_creds option.
			It is very userfull e.g with xlock. If you unlock
			the display then it will refresh your creds if
			possible.
   force_refresh	force the refresh_creds option.
   retain_creds or
   retain_tokens	Retain the credentials and tokens after session closed.
			Same as the retain_after_close option.
   use_authtok		Rely on tokens input by a previous module in the stack
			when changing passwords.  Primarily used if you're using
			pam_cracklib to screen out weak passwords.
   no_user_check	Don't bother checking if the login account corresponding
			to the principal exists or not, and use UID the service
			is executing under as the owner for any ccache files
			which get created.
   no_warn		Ignored.

This module was built and tested against MIT Kerberos 5 v1.2.3 and Heimdal 0.4e,
but it should only require v1.1.x. Because some configuration options touch
variables which are internal to the Kerberos libraries themselves,
it may require adjustments to build correctly with other implementations.

Updates: updated source and binary packages will always appear (however
infrequently) in Raw Hide (ftp://ftp.redhat.com/pub/redhat/linux/rawhide/).
The source tree can also be pulled directly from CVS off sources.redhat.com.
To check out a copy of the tree:
   cvs -d :pserver:anoncvs@elvis.redhat.com:/usr/local/CVS login
   cvs -d :pserver:anoncvs@elvis.redhat.com:/usr/local/CVS co pam_krb5
The anoncvs password is "anoncvs".

Caveat: pam_pwdb will cause things to fail if your user information isn't stored
in one of the databases it knows about (i.e., hesiod or LDAP).  Switch to
pam_unix if that happens.

Let me know if you have problems,

Nalin Dahyabhai <nalin@redhat.com>
23 July 2002

Balazs Gal <balsa@rit.bme.hu> /* Heimdal port */
Sat,  3 Aug 2002
