Provided by:
libpam-heimdal_2.6-1build1_i386 
NAME
pam_krb5 - Kerberos v5 PAM module
SYNOPSIS
auth sufficient pam_krb5.so ignore_root
session optional pam_krb5.so ignore_root
account required pam_krb5.so ignore_root
password optional pam_krb5.so ignore_root
DESCRIPTION
The Kerberos v5 service module for PAM, typically installed at
/lib/security/pam_krb5.so, provides functionality for the four PAM
operations: authentication, account management, session management, and
password management. pam_krb5.so is a shared object that is
dynamically loaded by the PAM subsystem as necessary, based on the
system PAM configuration. PAM is a system for plugging in external
authentication and session management modules so that each application
doesn’t have to know the best way to check user authentication or
create a user session on that system. For details on how to configure
PAM on your system, see the PAM man page, often pam(7).
Here are the actions of this module when called from each group:
auth
Provides implementations of pam_authenticate() and pam_setcred().
The former takes the username from the PAM session, prompts for the
user’s password (unless configured to use an already-entered
password), and then performs a Kerberos initial authentication,
storing the obtained credentials (if successful) in a temporary
ticket cache. The latter, depending on the flags it is called
with, either takes the contents of the temporary ticket cache and
writes it out to a persistant ticket cache owned by the user or
uses the temporary ticket cache to refresh an existing user ticket
cache.
After doing the initial authentication, the Kerberos PAM module
will attempt to obtain tickets for a key in the local system keytab
and then verify those tickets. Unless this step is performed, the
authentication is vulnerable to KDC spoofing, but it requires that
the system have a local key and that the PAM module be running as a
user that can read the keytab file (normally /etc/krb5.keytab. If
that keytab cannot be read or if no keys are found in it, the
default (potentially insecure) behavior is to skip this check. If
you want to instead fail authentication if the obtained tickets
cannot be checked, set "verify_ap_req_nofail" to true in the
[libdefaults] section of /etc/krb5.conf. Note that this will
affect applications other than this PAM module.
By default, whenever the user is authenticated, a basic
authorization check will also be done using krb5_kuserok(). The
default behavior of this function is to check the user’s account
for a .k5login file and, if one is present, ensure that the user’s
principal is listed in that file. If .k5login is not present, the
default check is to ensure that the user’s principal is in the
default local realm and the user portion of the principal matches
the account name (this can be changed by configuring a custom aname
to localname mapping in krb5.conf; see the Kerberos documentation
for details). This can be customized with several configuration
options; see below.
When pam_setcred() is called to initialize a new ticket cache, the
environment variable KRB5CCNAME is set to the path to that ticket
cache. By default, the cache will be named /tmp/krb5cc_UID_RANDOM
where UID is the user’s UID and RANDOM is six randomly-chosen
letters. This can be configured with the ccache and ccache_dir
options.
If pam_setcred() initializes a new ticket cache, it will also set
up that ticket cache so that it will be deleted when the PAM
session is closed. Normally, the calling program (login, sshd,
etc.) will run the user’s shell as a sub-process, wait for it to
exit, and then close the PAM session, thereby cleaning up the
user’s session.
session
Provides implementations of pam_open_session(), which is equivalent
to calling pam_setcred() with the PAM_ESTABLISH_CRED flag, and
pam_close_session(), which destroys the ticket cache created by
pam_setcred().
account
Provides an implementation of pam_acct_mgmt(). All it does is do
the same authorization check as performed by the pam_authenticate()
implementation described above.
password
Provides an implementation of pam_chauthtok(), which implements
password changes. The user is prompted for their existing password
(unless configured to use an already entered one) and the PAM
module then obtains credentials for the special Kerberos principal
"kadmin/changepw". It then prompts the user for a new password,
twice to ensure that the user entered it properly (again, unless
configured to use an already entered password), and then does a
Kerberos password change.
Unlike the normal Unix password module, this module will allow any
user to change any other user’s password if they know the old
password. Also, unlike the normal Unix password module, root will
always be prompted for the old password, since root has no special
status in Kerberos. (To change passwords in Kerberos without
knowing the old password, use kadmin(8) instead.)
Both the account and session management calls of the Kerberos v5 PAM
module will silently return success if called in the context of a PAM
session for a user who did not authenticate with Kerberos.
Note that this module assumes the network is available in order to do a
Kerberos authentication, and if the network is not available, some
Kerberos libraries have timeouts longer than the timeout imposed by the
login process. This means that using this module incautiously can make
it impossible to log on to console as root. For this reason, you
should always use the ignore_root or minimum_uid options, list a local
authentication module such as pam_unix first with a control field of
"sufficient" so that the Kerberos PAM module will be skipped if local
password authentication was successful.
This is not the same PAM module as the Kerberos PAM module available
from Sourceforge. It supports many of the same options, has some
additional options, and doesn’t support some of the options the
Sourceforge module does.
CONFIGURATION
The Kerberos v5 PAM module takes many options, not all of which are
relevant to every PAM group; options that are not relevant will be
silently ignored. Any of these options can be set in the PAM
configuration as arguments listed after "pam_krb5.so". Some of the
options can also be set in the system krb5.conf file; if this is
possible, it will be noted below in the option description.
To set a boolean option in the PAM configuration file, just give the
name of the option in the arguments. To set an option that takes an
argument, follow the option name with an equal sign (=) and the value,
with no separating whitespace. Whitespace in option arguments is not
supported in the PAM configuration.
To set an option for the PAM module in the system krb5.conf file, put
that option in the [appdefaults] section. The Kerberos v5 PAM module
will look for options either at the top level of the [appdefaults]
section or in a subsection named "pam", inside or outside a section for
the realm. For example, the following fragment of a krb5.conf file
would set forwardable to true, minimum_uid to 100, and set
ignore_k5login only if the realm is EXAMPLE.COM.
[appdefaults]
forwardable = true
pam = {
minimum_uid = 100
EXAMPLE.COM = {
ignore_k5login = true
}
}
For more information on the syntax of krb5.conf, see krb5.conf(5).
Note that options that depend on the realm will be set only on the
basis of the default realm, either as configured in krb5.conf(5) or as
set by the realm option described below. If the user authenticates to
an account qualified with a realm, that realm will not be used when
determining which options will apply.
There is no difference to the PAM module whether options are specified
at the top level or in a "pam" section; the "pam" section is supported
in case there are options that should be set for the PAM module but not
for other applications.
If the same option is set in krb5.conf and in the PAM configuration,
the latter takes precedent. Note, however, that due to the
configuration syntax, there’s no way to turn off a boolean option in
the PAM configuration that was turned on in krb5.conf.
ccache=<pattern>
Use <pattern> as the pattern for creating credential cache names.
<pattern> must be in the form <type>:<residual> where <type> and
the following colon are optional if a file cache should be used.
The special token %u, anywhere in <pattern>, is replaced with the
user’s numeric UID. The special token %p, anywhere in <pattern>,
is replaced with the current process ID.
If <pattern> ends in the literal string "XXXXXX" (six X’s), that
string will be replaced by randomly generated characters and the
ticket cache will be created using mkstemp(3). This is strongly
recommended if <pattern> points to a world-writable directory.
This option can be set in krb5.conf and is only applicable to the
auth and session groups.
ccache_dir=<directory>
Store user ticket caches in <directory> instead of in /tmp. The
algorithm for generating the ticket cache name is otherwise
unchanged.
This option can be set in krb5.conf and is only applicable to the
auth and session groups.
debug
Log more verbose trace and debugging information to syslog at
LOG_DEBUG priority, including entry and exit from each of the
external PAM interfaces (except pam_close_session).
This option can be set in krb5.conf.
forwardable
Obtain forwardable tickets. If set (to either true or false,
although it can only be set to false in krb5.conf), this overrides
the Kerberos library default set in the [libdefaults] section of
krb5.conf.
This option can be set in krb5.conf and is only applicable to the
auth group.
ignore_k5login
Never look for a .k5login file in the user’s home directory.
Instead, only check that the Kerberos principal maps to the local
account name. The default check is to ensure the realm matches the
local realm and the user portion of the principal matches the local
account name, but this can be customized by setting up an aname to
localname mapping in krb5.conf.
This option can be set in krb5.conf and is only applicable to the
auth and account groups.
ignore_root
Do not do anything if the username is "root". The authentication
and password calls will silently fail (allowing that status to be
ignored via a control of "optional" or "sufficient"), and the
account and session calls (including pam_setcred) will silently
succeed. This option is supported and will remain, but normally
you want to use minimum_uid instead.
This option can be set in krb5.conf.
minimum_uid=<uid>
Do not do anything if the authenticated account name corresponds to
a local account and that local account has a UID lower than <uid>.
If both of those conditions are true, the authentication and
password calls will silently fail (allowing that status to be
ignored via a control of "optional" or "sufficient"), and the
account and session calls (including pam_setcred) will silently
succeed. Using this option is highly recommended if you don’t need
to use Kerberos to authenticate password logins to the root account
(which isn’t recommended since Kerberos requires a network
connection).
This option can be set in krb5.conf.
no_ccache
Do not create a ticket cache after authentication. This option
shouldn’t be set in general, but is useful as part of the PAM
configuration for a particular service that uses PAM for
authentication but isn’t creating user sessions and doesn’t want
the overhead of ever writing the user credentials to disk. When
using this option, the application should only call
pam_authenticate(); other functions like pam_setcred() and
pam_start_session() don’t make sense with this option.
This option is only applicable to the auth group.
realm=<realm>
Obtain credentials in the specified realm rather than in the
default realm for this system. If this option is used, it should
be set for all groups being used for consistent results (although
the account group currently doesn’t care about realm). This will
not change authorization decisions. If the obtained credentials
are supposed to allow access to a shell account, the user will need
an appropriate .k5login file entry or the system will have to have
a custom aname_to_localname mapping.
renew_lifetime=<lifetime>
Obtain renewable tickets with a maximum renewable lifetime of
<lifetime>. <lifetime> should be a Kerberos lifetime string such
as "2d4h10m" or a time in minutes. If set, this overrides the
Kerberos library default set in the [libdefaults] section of
krb5.conf.
This option can be set in krb5.conf and is only applicable to the
auth group.
retain_after_close
Normally, the user’s ticket cache is destroyed when either
pam_end() or pam_close_session() is called by the authenticating
application so that ticket caches aren’t left behind after the user
logs out. In some cases, however, this isn’t desireable. (On
Solaris 8, for instance, the default behavior means login will
destroy the ticket cache before running the user’s shell.) If this
option is set, the PAM module will never destroy the user’s ticket
cache. If you set this, you may want to call kdestroy in the
shell’s logout configuration or run a temporary file removal
program to avoid accumulating hundreds of ticket caches in /tmp.
This option can be set in krb5.conf and is only applicable to the
auth and session groups.
search_k5login
Normally, the Kerberos implementation of pam_authenticate attempts
to obtain tickets for the authenticating username in the local
realm. If this option is set and the local user has a .k5login
file in their home directory, the module will instead open and read
that .k5login file, attempting to use the supplied password to
authenticate as each principal listed there in turn. If any of
those authentications succeed, the user will be successfully
authenticated; otherwise, authentication will fail. This option is
useful for allowing password authentication (via console or sshd
without GSS-API support) to shared accounts. If there is no
.k5login file, the behavior is the same as normal. Using this
option requires that the user’s .k5login file be readable at the
time of authentication.
This option can be set in krb5.conf and is only applicable to the
auth group.
try_first_pass
If the authentication module isn’t the first on the stack, and a
previous module obtained the user’s password, use that password to
authenticate the user without prompting them again. If that
authentication fails, fall back on prompting the user for their
password. This option has no effect if the authentication module
is first in the stack or if no previous module obtained the user’s
password.
This option is only applicable to the auth and password groups.
For the password group, it applies to both the old and new
passwords.
use_authtok
Use the password obtained by a previous authentication module to
authenticate the user and any password obtained by a previous
password module for the new password when changing passwords. If
these passwords aren’t available, fail. Never prompt the user for
a password under any circumstances. This can be used to require
passwords be checked by another, prior module, such as
pam_cracklib.
This option is only applicable to the auth and password groups.
use_first_pass
Use the password obtained by a previous authentication module to
authenticate the user, and the password obtained by a previous
password module as the new password when changing passwords,
without prompting the user again again. If no previous module
obtained the user’s password for either an authentication or
password change, fall back on prompting the user. If a previous
module did obtain the user’s password but authentication with that
password fails, fail without further prompting the user.
This option is only applicable to the auth and password groups.
ENVIRONMENT
KRB5CCNAME
Set by pam_setcred() with the PAM_ESTABLISH_CRED option, and
therefore also by pam_open_session(), to point to the new
credential cache for the user. See the ccache and ccache_dir
options.
PAM_KRB5CCNAME
Set by pam_authenticate() to point to the temporary ticket cache
used for authentication (unless the no_ccache option was given).
pam_setcred() then uses that environment variable to locate the
temporary cache even if it was not called in the same PAM session
as pam_authenticate() (a problem with sshd running in some modes).
This environment variable is only used internal to the PAM module.
FILES
/tmp/krb5cc_UID_RANDOM
The default credential cache name. UID is the decimal UID of the
local user and RANDOM is a random six-character string. The
pattern may be changed with the ccache option and the directory
with the ccache_dir option.
/tmp/krb5cc_pam_RANDOM
The credential cache name used for the temporary credential cache
created by pam_authenticate(). This cache is removed again when
the PAM session is ended or when pam_setcred() is called and will
normally not be user-visible. RANDOM is a random six-character
string.
~/.k5login
File containing Kerberos principals that are allowed access to that
account.
SEE ALSO
kadmin(8), kdestroy(1), krb5.conf(5), pam(7), passwd(1), syslog(3)