Provided by:
libpam-krb5_1.2.0-3_i386 
NAME
pam_krb5 - Kerberos 5 PAM module
SYNOPSIS
auth sufficient pam_krb5.so ignore_root
account required pam_krb5.so ignore_root
password optional pam_krb5.so ignore_root
session optional pam_krb5.so ignore_root
DESCRIPTION
The Kerberos 5 service module for PAM, typically
/lib/security/pam_krb5.so, provides functionality for three PAM
categories: authentication, account management, session management, and
password management.
The pam_krb5.so module is a shared object that can be dynamically
loaded to provide the necessary functionality upon demand. Its path is
specified in the PAM configuration file.
Kerberos 5 Authentication Module
The Kerberos 5 authentication component provides functions to verify
the identity of a user. (pam_sm_authenticate()) and to set user
specific credentials (pam_sm_setcred()). pam_sm_authenticate()
converts the supplied username into a Kerberos principal, by appending
the default local realm name. It also supports usernames with explicit
realm names.
It prompts the user for a password and obtains a new Kerberos TGT for
the principal. The TGT is verified by obtaining a service ticket for
the local host.
The pam_sm_setcred() function stores the newly acquired credentials in
a credentials cache, and sets the environment variable KRB5CCNAME
appropriately. This module destroys the credentials cache when the PAM
data is cleaned up. Thus, you should set close_sessions to yes in
/etc/login.defs.
If the authentication is done as root and a local keytab is available,
pam_krb5.so will do a proper Kerberos authentication by using the
Kerberos TGT acquired to obtain a service ticket and then validate the
service ticket against a local keytab. If there is no local keytab or
if the keytab file (/etc/krb5.keytab) is not readable, this step will
be skipped. Without performing this step, authentication is vulnerable
to KDC spoofing. If a keytab is available, the module first looks for
a principal named host/machine where machine is the fully qualified
local hostname. If that principal isn’t available, it looks for
service/machine where service is the PAM service used (the first
argument to pam_start()) and machine is the same as above.
The following options may be passed to the authentication module:
debug syslog(3) debugging information at LOG_DEBUG level.
use_first_pass If the authentication module is not the first in the
stack, and a previous module obtained the user’s
password, that password is used to authenticate the
user. If this fails, the authentication module returns
failure without prompting the user for a password. This
option has no effect if the authentication module is the
first in the stack, or if no previous modules obtained
the user’s password.
try_first_pass This option is similar to the use_first_pass option,
except that if the previously obtained password fails,
the user is prompted for another password.
forwardable Obtain forwardable Kerberos credentials for the user.
no_ccache Do not save the obtained credentials in a credentials
cache. This is a useful option if the authentication
module is used for services such as ftp or pop, where
the user would not be able to destroy them. [This is not
a recommendation to use the module for those services.]
ignore_root Never attempt to authenticate the user "root". Always
fail immediately if that user is being authenticated;
presumably the PAM stack will fall back to some other
mechanism.
search_k5login Normally, the authentication module attempts to
authenticate as a Kerberos principal derived from the
username by appending the default realm. Verification
of the presence of that Kerberos principal in the user’s
.k5login file can then be done via the account
management module. When this option is given and a
.k5login file is present, the provided password is
instead used to attempt to authenticate as each Kerberos
principal listed in the .k5login file in turn. If there
is no .k5login file, the behavior is the same as normal.
This may be useful when there is no simple mapping from
local username to Kerberos principal name, but requires
the .k5login file be readable at the time of
authentication (and therefore may not work with schemes
such as sshd’s privilege separation).
Kerberos 5 Session Management Module
The Kerberos 5 session management component provides functions to
initiate (pam_sm_open_session()) and terminate (pam_sm_close_session())
sessions. This module takes all of the same options as the
authentication module and will authenticate the user if authentication
has not already been established. In addition, it takes the following
options specific to this module:
ccache=<name>
Use <name> as the credentials cache. <name> must be in the form
type:residual (where type is optional if a file cache is used).
The special tokens %u, to designate the decimal uid of the user,
and %p, to designate the current process id, can be used in
<name>. If <name> ends with the literal string XXXXXX (six
X’s), that string will be replaced by randomly generated
characters and the ticket cache opened via mkstemp. This is
strongly recommended if <name> points to a world-writable
directory.
ccache_dir=<dir>
Put the ticket cache in <dir> instead of the default of /tmp.
Ignored if ccache is also set.
Kerberos 5 Account Management Module
The Kerberos 5 account management component provides a function to
perform account management, pam_sm_acct_mgmt(). The function verifies
that the authenticated principal is allowed to login to the local user
account by calling krb5_kuserok() (which checks the user’s .k5login
file). Note that this is also done by pam_sm_authenticate() and
pam_sm_setcred().
If the user didn’t log on using krb5, this function silently succeeds.
The following options may be passed to the account module:
ignore_root Skip any attempt to validate the root account and just
succeed quietly. Presumably whatever validation is
necessary will be handled by another module in the PAM
stack.
Kerberos 5 Password Management Module
The Kerberos 5 password management component provides a function to
change passwords (pam_sm_chauthtok()). The username supplied (the user
running the passwd(1) command, or the username given as an argument) is
mapped into a Kerberos principal name, using the same technique as in
the authentication module. Note that if a realm name was explicitly
supplied during authentication, but not during a password change, the
mapping done by the password management module may not result in the
same principal as was used for authentication.
Unlike when changing a unix password, the password management module
will allow any user to change any principal’s password (if the user
knows the principal’s old password, of course). Also unlike unix, root
is always prompted for the principal’s old password.
The password management module uses the same heuristics as kpasswd(1)
to determine how to contact the Kerberos password server.
The following options may be passed to the password management module:
debug syslog(3) debugging information at LOG_DEBUG level.
use_first_pass If the password management module is not the first in
the stack, and a previous module obtained the user’s old
password, that password is used to authenticate the
user. If this fails, the password management module
returns failure without prompting the user for the old
password. If successful, the new password entered to
the previous module is also used as the new Kerberos
password. If the new password fails, the password
management module returns failure without prompting the
user for a new password.
try_first_pass This option is similar to the use_first_pass option,
except that if the previously obtained old or new
passwords fail, the user is prompted for them.
ignore_root Do not try to change passwords for the root user, just
fail immediately.
ENVIRONMENT
KRB5CCNAME Location of the credentials cache.
FILES
/tmp/krb5cc_[uid]_[rand]
default credentials cache ([uid] is the decimal UID of the user
and [rand] is a random string). The directory in which it is
stored may be changed with the ccache_dir option.
~/.k5login
file containing Kerberos principals that are allowed access.
SEE ALSO
kdestroy(1), passwd(1), pam(7), syslog(3).
NOTES
Applications should not call pam_authenticate() more than once between
calls to pam_start() and pam_end() when using the Kerberos 5 PAM
module.