~ubuntu-branches/ubuntu/quantal/libpam-krb5/quantal-201405130549

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PAM_KRB5 5"
.TH PAM_KRB5 5 "2010-12-31" "4.4" "pam-krb5"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pam_krb5 \- Kerberos v5 PAM module
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  auth            sufficient      pam_krb5.so minimum_uid=1000
\&  session         required        pam_krb5.so minimum_uid=1000
\&  account         required        pam_krb5.so minimum_uid=1000
\&  password        sufficient      pam_krb5.so minimum_uid=1000
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Kerberos v5 service module for \s-1PAM\s0, typically installed at
\&\fI/lib/security/pam_krb5.so\fR, provides functionality for the four \s-1PAM\s0
operations: authentication, account management, session management, and
password management.  \fIpam_krb5.so\fR is a shared object that is
dynamically loaded by the \s-1PAM\s0 subsystem as necessary, based on the system
\&\s-1PAM\s0 configuration.  \s-1PAM\s0 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 \s-1PAM\s0 on your
system, see the \s-1PAM\s0 man page, often \fIpam\fR\|(7).
.PP
Here are the actions of this module when called from each group:
.IP "auth" 4
.IX Item "auth"
Provides implementations of \fIpam_authenticate()\fR and \fIpam_setcred()\fR.  The
former takes the username from the \s-1PAM\s0 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 persistent ticket cache
owned by the user or uses the temporary ticket cache to refresh an
existing user ticket cache.
.Sp
After doing the initial authentication, the Kerberos \s-1PAM\s0 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 \s-1KDC\s0 spoofing, but it requires that the system have a
local key and that the \s-1PAM\s0 module be running as a user that can read the
keytab file (normally \fI/etc/krb5.keytab\fR.  You can point the Kerberos \s-1PAM\s0
module at a different keytab with the \fIkeytab\fR option.  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
\&\f(CW\*(C`verify_ap_req_nofail\*(C'\fR to true in the [libdefaults] section of
\&\fI/etc/krb5.conf\fR.  Note that this will affect applications other than
this \s-1PAM\s0 module.
.Sp
By default, whenever the user is authenticated, a basic authorization
check will also be done using \fIkrb5_kuserok()\fR.  The default behavior of
this function is to check the user's account for a \fI.k5login\fR file and,
if one is present, ensure that the user's principal is listed in that
file.  If \fI.k5login\fR 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 \fIkrb5.conf\fR; see the Kerberos
documentation for details).  This can be customized with several
configuration options; see below.
.Sp
If the username provided to \s-1PAM\s0 contains an \f(CW\*(C`@\*(C'\fR and Kerberos can,
treating the username as a principal, map it to a local account name,
\&\fIpam_authenticate()\fR will change the \s-1PAM\s0 user to that local account name.
This allows users to log in with their Kerberos principal and let Kerberos
do the mapping to an account.  Be aware, however, that this facility
cannot be used with OpenSSH.  OpenSSH will reject usernames that don't
match local accounts before this remapping can be done and will pass an
invalid password to the \s-1PAM\s0 module.  Also be aware that several other
common \s-1PAM\s0 modules, such as pam_securetty, expect to be able to look up
the user with \fIgetpwnam()\fR and cannot be called before pam_krb5 if this
feature is used.
.Sp
When \fIpam_setcred()\fR is called to initialize a new ticket cache, the
environment variable \s-1KRB5CCNAME\s0 is set to the path to that ticket cache.
By default, the cache will be named \fI/tmp/krb5cc_UID_RANDOM\fR where \s-1UID\s0 is
the user's \s-1UID\s0 and \s-1RANDOM\s0 is six randomly-chosen letters.  This can be
configured with the \fIccache\fR and \fIccache_dir\fR options.
.Sp
If \fIpam_setcred()\fR initializes a new ticket cache, it will also set up that
ticket cache so that it will be deleted when the \s-1PAM\s0 session is closed.
Normally, the calling program (\fBlogin\fR, \fBsshd\fR, etc.) will run the
user's shell as a sub-process, wait for it to exit, and then close the \s-1PAM\s0
session, thereby cleaning up the user's session.
.IP "session" 4
.IX Item "session"
Provides implementations of \fIpam_open_session()\fR, which is equivalent to
calling \fIpam_setcred()\fR with the \s-1PAM_ESTABLISH_CRED\s0 flag, and
\&\fIpam_close_session()\fR, which destroys the ticket cache created by
\&\fIpam_setcred()\fR.
.IP "account" 4
.IX Item "account"
Provides an implementation of \fIpam_acct_mgmt()\fR.  All it does is do the same
authorization check as performed by the \fIpam_authenticate()\fR implementation
described above.
.IP "password" 4
.IX Item "password"
Provides an implementation of \fIpam_chauthtok()\fR, which implements password
changes.  The user is prompted for their existing password (unless
configured to use an already entered one) and the \s-1PAM\s0 module then obtains
credentials for the special Kerberos principal \f(CW\*(C`kadmin/changepw\*(C'\fR.  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.
.Sp
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
\&\fIkadmin\fR\|(8) instead.)
.PP
Both the account and session management calls of the Kerberos v5 \s-1PAM\s0
module will return \s-1PAM_IGNORE\s0 if called in the context of a \s-1PAM\s0 session
for a user who did not authenticate with Kerberos (a return code of
\&\f(CW\*(C`ignore\*(C'\fR in the Linux \s-1PAM\s0 configuration language).
.PP
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 \fIignore_root\fR or \fIminimum_uid\fR options, list a local
authentication module such as \fBpam_unix\fR first with a control field of
\&\f(CW\*(C`sufficient\*(C'\fR so that the Kerberos \s-1PAM\s0 module will be skipped if local
password authentication was successful.
.PP
This is not the same \s-1PAM\s0 module as the Kerberos \s-1PAM\s0 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.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The Kerberos v5 \s-1PAM\s0 module takes many options, not all of which are
relevant to every \s-1PAM\s0 group; options that are not relevant will be
silently ignored.  Any of these options can be set in the \s-1PAM\s0
configuration as arguments listed after \f(CW\*(C`pam_krb5.so\*(C'\fR.  Some of the
options can also be set in the system \fIkrb5.conf\fR file; if this is
possible, it will be noted below in the option description.
.PP
To set a boolean option in the \s-1PAM\s0 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 \s-1PAM\s0 configuration.
.PP
To set an option for the \s-1PAM\s0 module in the system \fIkrb5.conf\fR file, put
that option in the [appdefaults] section.  The Kerberos v5 \s-1PAM\s0 module will
look for options either at the top level of the [appdefaults] section or
in a subsection named \f(CW\*(C`pam\*(C'\fR, inside or outside a section for the realm.
For example, the following fragment of a \fIkrb5.conf\fR file would set
\&\fIforwardable\fR to true, \fIminimum_uid\fR to 1000, and set \fIignore_k5login\fR
only if the realm is \s-1EXAMPLE\s0.COM.
.PP
.Vb 8
\&    [appdefaults]
\&        forwardable = true
\&        pam = {
\&            minimum_uid = 1000
\&            EXAMPLE.COM = {
\&                ignore_k5login = true
\&            }
\&        }
.Ve
.PP
For more information on the syntax of \fIkrb5.conf\fR, see \fIkrb5.conf\fR\|(5).
Note that options that depend on the realm will be set only on the basis
of the default realm, either as configured in \fIkrb5.conf\fR\|(5) or as set by
the \fIrealm\fR 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.
.PP
There is no difference to the \s-1PAM\s0 module whether options are specified at
the top level or in a \f(CW\*(C`pam\*(C'\fR section; the \f(CW\*(C`pam\*(C'\fR section is supported in
case there are options that should be set for the \s-1PAM\s0 module but not for
other applications.
.PP
If the same option is set in \fIkrb5.conf\fR and in the \s-1PAM\s0 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 \s-1PAM\s0
configuration that was turned on in \fIkrb5.conf\fR.
.SS "Authorization"
.IX Subsection "Authorization"
.IP "alt_auth_map=<format>" 4
.IX Item "alt_auth_map=<format>"
This functions similarly to the \fIsearch_k5login\fR option.  The <format>
argument is used as the authentication Kerberos principal, with any \f(CW%s\fR
in <format> replaced with the username.  If the username contains an \f(CW\*(C`@\*(C'\fR,
only the part of the username before the realm is used to replace \f(CW%s\fR
and the realm is appended to the result.  There is no quote removal.
.Sp
If this option is present, the default behavior is to try this alternate
principal first and then fall back to the standard behavior if it fails.
The primary usage is to allow alternative principals to be used for
authentication in programs like \fBsudo\fR.  Most examples will look like:
.Sp
.Vb 1
\&    alt_auth_map=%s/root
.Ve
.Sp
which attempts authentication as the root instance of the username first
and then falls back to the regular username (but see \fIforce_alt_auth\fR and
\&\fIonly_alt_auth\fR).
.Sp
This option can be set in \fIkrb5.conf\fR, although normally it doesn't make
sense to do that; normally it is used in the \s-1PAM\s0 options of configuration
for specific programs.  It is only applicable to the auth and account
groups.  If this option is set for the auth group, be sure to set it for
the account group as well or account authorization may fail.
.IP "force_alt_auth" 4
.IX Item "force_alt_auth"
This option is used with \fIalt_auth_map\fR and forces authentication as the
mapped principal if that principal exists in the \s-1KDC\s0.  Only if the \s-1KDC\s0
returns principal unknown does the Kerberos \s-1PAM\s0 module fall back to normal
authentication.  This can be used to force authentication with an
alternate instance.  If \fIalt_auth_map\fR is not set, it has no effect.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "ignore_k5login" 4
.IX Item "ignore_k5login"
Never look for a \fI.k5login\fR 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 \fIkrb5.conf\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and account groups.
.IP "ignore_root" 4
.IX Item "ignore_root"
Do not do anything if the username is \f(CW\*(C`root\*(C'\fR.  The authentication and
password calls will silently fail (allowing that status to be ignored via
a control of \f(CW\*(C`optional\*(C'\fR or \f(CW\*(C`sufficient\*(C'\fR), and the account and session
calls (including pam_setcred) will return \s-1PAM_IGNORE\s0, telling the \s-1PAM\s0
library to proceed as if they weren't mentioned in the \s-1PAM\s0 configuration.
This option is supported and will remain, but normally you want to use
\&\fIminimum_uid\fR instead.
.Sp
This option can be set in \fIkrb5.conf\fR.
.IP "minimum_uid=<uid>" 4
.IX Item "minimum_uid=<uid>"
Do not do anything if the authenticated account name corresponds to a
local account and that local account has a \s-1UID\s0 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
\&\f(CW\*(C`optional\*(C'\fR or \f(CW\*(C`sufficient\*(C'\fR), and the account and session calls
(including pam_setcred) will return \s-1PAM_IGNORE\s0, telling the \s-1PAM\s0 library to
proceed as if they weren't mentioned in the \s-1PAM\s0 configuration.
.Sp
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).  It provides
some defense in depth against user principals that happen to match a
system account incorrectly authenticating as that system account.
.Sp
This option can be set in \fIkrb5.conf\fR.
.IP "only_alt_auth" 4
.IX Item "only_alt_auth"
This option is used with \fIalt_auth_map\fR and forces the use of the mapped
principal for authentication.  It disables fallback to normal
authentication in all cases and overrides \fIsearch_k5login\fR and
\&\fIforce_alt_auth\fR.  If \fIalt_auth_map\fR is not set, it has no effect and
the standard authentication behavior is used.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "search_k5login" 4
.IX Item "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 \fI.k5login\fR file in their home
directory, the module will instead open and read that \fI.k5login\fR 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
\&\fI.k5login\fR file, the behavior is the same as normal.  Using this option
requires that the user's \fI.k5login\fR file be readable at the time of
authentication.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.SS "Kerberos Behavior"
.IX Subsection "Kerberos Behavior"
.IP "fast_ccache=<ccache_name>" 4
.IX Item "fast_ccache=<ccache_name>"
Attempt to use Flexible Authenticatin Secure Tunneling (\s-1FAST\s0) to protect
the authentication.  \s-1FAST\s0 is a mechanism to protect Kerberos against
password guessing attacks and provide other security improvements.  To
work, \s-1FAST\s0 requires that a ticket be obtained with a strong key to protect
exchanges with potentially weaker user passwords.  This configuration
value should be set to a credential cache containing such a ticket.
.Sp
If <ccache_name> names a ticket cache that is readable by the
authenticating process and has tickets then \s-1FAST\s0 will be attempted.  The
easiest way to use this option is to use a program like \fBk5start\fR to
maintain a ticket cache using the host's keytab.  This ticket cache should
normally only be readable by root, so this option will not be able to
protect authentications done as non-root users (such as screensavers).
.Sp
If no credentials are present in the ticket cache, or if the ticket cache
does not exist or is not readable, \s-1FAST\s0 will not used and authentication
will proceed as normal.  However, if the credentials in that ticket cache
are expired, authentication will fail if the \s-1KDC\s0 supports \s-1FAST\s0.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "forwardable" 4
.IX Item "forwardable"
Obtain forwardable tickets.  If set (to either true or false, although it
can only be set to false in \fIkrb5.conf\fR), this overrides the Kerberos
library default set in the [libdefaults] section of \fIkrb5.conf\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "keytab=<path>" 4
.IX Item "keytab=<path>"
Specifies the keytab to use when validating the user's credentials.  The
default is the default system keytab (normally \fI/etc/krb5.keytab\fR), which
is usually only readable by root.  Applications not running as root that
use this \s-1PAM\s0 module for authentication may wish to point it to another
keytab the application can read.  The first principal found in the keytab
will be used as the principal for credential verification.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "realm=<realm>" 4
.IX Item "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 \fI.k5login\fR file entry or the
system will have to have a custom aname_to_localname mapping.
.IP "renew_lifetime=<lifetime>" 4
.IX Item "renew_lifetime=<lifetime>"
Obtain renewable tickets with a maximum renewable lifetime of <lifetime>.
<lifetime> should be a Kerberos lifetime string such as \f(CW\*(C`2d4h10m\*(C'\fR or a
time in minutes.  If set, this overrides the Kerberos library default set
in the [libdefaults] section of \fIkrb5.conf\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "ticket_lifetime=<lifetime>" 4
.IX Item "ticket_lifetime=<lifetime>"
Obtain tickets with a maximum lifetime of <lifetime>.  <lifetime> should
be a Kerberos lifetime string such as \f(CW\*(C`2d4h10m\*(C'\fR or a time in minutes.  If
set, this overrides the Kerberos library default set in the [libdefaults]
section of \fIkrb5.conf\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.SS "\s-1PAM\s0 Behavior"
.IX Subsection "PAM Behavior"
.IP "clear_on_fail" 4
.IX Item "clear_on_fail"
When changing passwords, \s-1PAM\s0 first does a preliminary check through the
complete password stack, and then calls each module again to do the
password change.  After that preliminary check, the order of module
invocation is fixed.  This means that even if the Kerberos v5 password
change fails (or if one of the other password changes in the stack fails),
other password \s-1PAM\s0 modules in the stack will still be called even if the
failing module is marked required or requisite.  When using multiple
password \s-1PAM\s0 modules to synchronize passwords between multiple systems
when they change, this behavior can cause unwanted differences between the
environments.
.Sp
Setting this option provides a way to work around this behavior.  If this
option is set and a Kerberos password change is attempted and fails (due
to network errors or password strength checking on the \s-1KDC\s0, for example),
this module will clear the stored password in the \s-1PAM\s0 stack.  This will
force any subsequent modules that have use_authtok set to fail so that
those environments won't get out of sync with the password in Kerberos.
The Kerberos v5 \s-1PAM\s0 module will not meddle with the stored password if it
skips the user due to configuration such as minimum_uid.
.Sp
Unfortunately, setting this option interferes with other desirable \s-1PAM\s0
configurations, such as attempting to change the password in Kerberos
first and falling back on the local Unix password database if that fails.
It therefore isn't the default.  Turn it on (and list pam_krb5 first after
pam_cracklib if used) when synchronizing passwords between multiple
environments.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the
password group.
.IP "debug" 4
.IX Item "debug"
Log more verbose trace and debugging information to syslog at \s-1LOG_DEBUG\s0
priority, including entry and exit from each of the external \s-1PAM\s0
interfaces (except pam_close_session).
.Sp
This option can be set in \fIkrb5.conf\fR.
.IP "defer_pwchange" 4
.IX Item "defer_pwchange"
By default, pam\-krb5 lets the Kerberos library handle prompting for a
password change if an account's password is expired during the auth
group.  If this fails, \fIpam_authenticate()\fR returns an error.
.Sp
According to the \s-1PAM\s0 standard, this is not the correct way to handle
expired passwords.  Instead, \fIpam_authenticate()\fR should return success
without attempting a password change, and then \fIpam_acct_mgmt()\fR should
return \s-1PAM_NEW_AUTHTOK_REQD\s0, at which point the calling application is
responsible for either rejecting the authentication or calling
\&\fIpam_chauthtok()\fR.  However, following the standard requires that all
applications call \fIpam_acct_mgmt()\fR and check its return status; otherwise,
expired accounts may be able to successfully authenticate.  Many
applications do not do this.
.Sp
If this option is set, pam\-krb5 uses the fully correct \s-1PAM\s0 mechanism for
handling expired accounts instead of failing in \fIpam_authenticate()\fR.  Due
to the security risk of widespread broken applications, be very careful
about enabling this option.  It should normally only be turned on to solve
a specific problem (such as using Solaris Kerberos libraries that don't
support prompting for password changes during authentication), and then
only for specific applications known to call \fIpam_acct_mgmt()\fR and check its
return status properly.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "fail_pwchange" 4
.IX Item "fail_pwchange"
By default, pam\-krb5 lets the Kerberos library handle prompting for a
password change if an account's password is expired during the auth
group.  If this option is set, expired passwords are instead treated as an
authentication failure identical to an incorrect password.  Also see
\&\fIdefer_pwchange\fR and \fIforce_pwchange\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.IP "force_pwchange" 4
.IX Item "force_pwchange"
If this option is set and authentication fails with a Kerberos error
indicating the user's password is expired, attempt to immediately change
their password during the authenticate step.  Under normal circumstances,
this is unnecessary.  Most Kerberos libraries will do this for you, and
setting this option will prompt the user twice to change their password if
the first attempt (done by the Kerberos library) fails.  However, some
system Kerberos libraries (such as Solaris's) have password change
prompting disabled in the Kerberos library; on those systems, you can set
this option to simulate the normal library behavior.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
group.
.SS "\s-1PKINIT\s0"
.IX Subsection "PKINIT"
.IP "pkinit_anchors=<anchors>" 4
.IX Item "pkinit_anchors=<anchors>"
When doing \s-1PKINIT\s0 authentication, use <anchors> as the client trust
anchors.  This is normally a reference to a file containing the trusted
certificate authorities.  This option is only used if \fItry_pkinit\fR or
\&\fIuse_pkinit\fR are set.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "pkinit_prompt" 4
.IX Item "pkinit_prompt"
Before attempting \s-1PKINIT\s0 authentication, prompt the user to insert a smart
card.  You may want to set this option for programs such as
\&\fBgnome-screensaver\fR that call \s-1PAM\s0 as soon as the mouse is touched and
don't give the user an opportunity to enter the smart card first.  Any
information entered at the first prompt is ignored.  If \fItry_pkinit\fR is
set, a user who wishes to use a password instead can just press Enter and
then enter their password as normal.  This option is only used if
\&\fItry_pkinit\fR or \fIuse_pkinit\fR are set.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "pkinit_user=<userid>" 4
.IX Item "pkinit_user=<userid>"
When doing \s-1PKINIT\s0 authentication, use <userid> as the user \s-1ID\s0.  The value
of this string is highly dependent on the type of \s-1PKINIT\s0 implementation
you're using, but will generally be something like:
.Sp
.Vb 1
\&    PKCS11:/usr/lib/pkcs11/lib/soft\-pkcs11.so
.Ve
.Sp
to specify the module to use with a smart card.  It may also point to a
user certificate or to other types of user IDs.  See the Kerberos library
documentation for more details.  This option is only used if \fItry_pkinit\fR
or \fIuse_pkinit\fR are set.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "preauth_opt=<option>" 4
.IX Item "preauth_opt=<option>"
Sets a preauth option (currently only applicable when built with \s-1MIT\s0
Kerberos).  <option> is either a key/value pair with the key separated
from the value by \f(CW\*(C`=\*(C'\fR or a boolean option (in which case it's turned
on).  In \fIkrb5.conf\fR, multiple options should be separated by
whitespace.  In the \s-1PAM\s0 configuration, this option can be given multiple
times to set multiple options.  In either case, <option> may not contain
whitespace.
.Sp
The primary use of this option, at least in the near future, will be to
set options for the \s-1MIT\s0 Kerberos \s-1PKINIT\s0 support.  For the full list of
possible options, see the \s-1PKINIT\s0 plugin documentation.  At the time of
this writing, \f(CW\*(C`X509_user_identity\*(C'\fR is equivalent to \fIpkinit_user\fR and
\&\f(CW\*(C`X509_anchors\*(C'\fR is equivalent to \fIpkinit_anchors\fR.  \f(CW\*(C`flag_DSA_PROTOCOL\*(C'\fR
can only be set via this option.
.Sp
Any settings made with this option are applied after the \fIpkinit_anchors\fR
and \fIpkinit_user\fR options, so if an equivalent setting is made via
\&\fIpreauth_opt\fR, it will probably override the other setting.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.  Note that there is no way to remove a setting made
in \fIkrb5.conf\fR using the \s-1PAM\s0 configuration, but options set in the \s-1PAM\s0
configuration are applied after options set in \fIkrb5.conf\fR and therefore
may override earlier settings.
.IP "try_pkinit" 4
.IX Item "try_pkinit"
Attempt \s-1PKINIT\s0 authentication before trying a regular password.  You will
probably also need to set the \fIpkinit_user\fR configuration option.  If
\&\s-1PKINIT\s0 fails, the \s-1PAM\s0 module will fall back on regular password
authentication.  This option is currently only supported if pam\-krb5 was
built against Heimdal 0.8rc1 or later or \s-1MIT\s0 Kerberos 1.6.3 or later.
.Sp
If this option is set and pam\-krb5 is built against \s-1MIT\s0 Kerberos, and
\&\s-1PKINIT\s0 fails and the module falls back to password authentication, the
user's password will not be stored in the \s-1PAM\s0 stack for subsequent
modules.  This is a bug in the interaction between the module and \s-1MIT\s0
Kerberos that requires some rearchitecting of the \s-1PKINIT\s0 authentication
method to fix.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "use_pkinit" 4
.IX Item "use_pkinit"
Require \s-1PKINIT\s0 authentication.  You will probably also need to set the
\&\fIpkinit_user\fR configuration option.  If \s-1PKINIT\s0 fails, authentication will
fail.  This option is currently only supported if pam\-krb5 was built
against Heimdal 0.8rc1 or later.  \s-1MIT\s0 Kerberos doesn't provide a method to
enforce use of \s-1PKINIT\s0, so \fItry_pkinit\fR must be used with that
implementation instead.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.SS "Prompting"
.IX Subsection "Prompting"
.IP "banner=<banner>" 4
.IX Item "banner=<banner>"
By default, the prompts when a user changes their password are:
.Sp
.Vb 3
\&    Current Kerberos password:
\&    Enter new Kerberos password:
\&    Retype new Kerberos password:
.Ve
.Sp
The string \*(L"Kerberos\*(R" is inserted so that users aren't confused about
which password they're changing.  Setting this option replaces the word
\&\*(L"Kerberos\*(R" with whatever this option is set to.  Setting this option to
the empty string removes the word before \*(L"password:\*(R" entirely.
.Sp
If set in the \s-1PAM\s0 configuration, <banner> may not contain whitespace.  If
you want a value containing whitespace, set it in \fIkrb5.conf\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the
password group.
.IP "expose_account" 4
.IX Item "expose_account"
By default, the Kerberos \s-1PAM\s0 module password prompt is simply
\&\*(L"Password:\*(R".  This avoids leaking any information about the system realm
or account to principal conversions.  If this option is set, the string
\&\*(L"for <principal>\*(R" is added before the colon, where <principal> is the
user's principal.  This string is also added before the colon on prompts
when changing the user's password.
.Sp
Enabling this option with ChallengeResponseAuthentication enabled in
OpenSSH may cause problems for some ssh clients that only recognize
\&\*(L"Password:\*(R" as a prompt.  This option is automatically disabled if
\&\fIsearch_k5login\fR is enabled since the principal displayed would be
inaccurate.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and password groups.
.IP "force_first_pass" 4
.IX Item "force_first_pass"
Use the password obtained by a previous authentication or password module
to authenticate the user without prompting the user again.  If no previous
module obtained the user's password, fail without prompting the user.
Also see \fItry_first_pass\fR and \fIuse_first_pass\fR for weaker versions of
this option.
.Sp
This option is only applicable to the auth and password groups.  For the
password group, it applies only to the old password.  See \fIuse_authtok\fR
for a similar setting for the new password.
.IP "prompt_principal" 4
.IX Item "prompt_principal"
Before prompting for the user's password (or using the previously entered
password, if \fItry_first_pass\fR, \fIuse_first_pass\fR, or \fIforce_first_pass\fR
are set), prompt the user for the Kerberos principal to use for
authentication.  This allows the user to authenticate with a different
principal than the one corresponding to the local username, provided that
either a \fI.k5login\fR file or local Kerberos principal to account mapping
authorize that principal to access the local account.
.Sp
Be cautious when using this configuration option and don't use it with
OpenSSH PasswordAuthentication, only ChallengeResponseAuthentication.
Some PAM-enabled applications expect \s-1PAM\s0 modules to only prompt for
passwords and may even blindly give the password to the first prompt, no
matter what it is.  Such applications, in combination with this option,
may expose the user's password in log messages and Kerberos requests.
.IP "try_first_pass" 4
.IX Item "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.  Also see \fIuse_first_pass\fR and
\&\fIforce_first_pass\fR for stronger versions of this option.
.Sp
This option is only applicable to the auth and password groups.  For the
password group, it applies only to the old password.
.IP "use_authtok" 4
.IX Item "use_authtok"
Use the new password obtained by a previous password module when changing
passwords rather than prompting for the new password.  If the new password
isn't available, fail.  This can be used to require passwords be checked
by another, prior module, such as \fBpam_cracklib\fR.
.Sp
This option is only applicable to the password group.
.IP "use_first_pass" 4
.IX Item "use_first_pass"
Use the password obtained by a previous authentication module to
authenticate the user without prompting the user 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.  Also see
\&\fItry_first_pass\fR and \fIforce_first_pass\fR for other versions of this
option.
.Sp
This option is only applicable to the auth and password groups.  For the
password group, it applies only to the old password.  See \fIuse_authtok\fR
for a similar setting for the new password.
.SS "Ticket Caches"
.IX Subsection "Ticket Caches"
.IP "ccache=<pattern>" 4
.IX Item "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 \f(CW%u\fR, anywhere in <pattern>, is replaced with the user's numeric
\&\s-1UID\s0.  The special token \f(CW%p\fR, anywhere in <pattern>, is replaced with the
current process \s-1ID\s0.
.Sp
If <pattern> ends in the literal string \f(CW\*(C`XXXXXX\*(C'\fR (six X's), that string
will be replaced by randomly generated characters and the ticket cache
will be created using \fImkstemp\fR\|(3).  This is strongly recommended if
<pattern> points to a world-writable directory.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and session groups.
.IP "ccache_dir=<directory>" 4
.IX Item "ccache_dir=<directory>"
Store user ticket caches in <directory> instead of in \fI/tmp\fR.  The
algorithm for generating the ticket cache name is otherwise unchanged.
<directory> may be prefixed with \f(CW\*(C`FILE:\*(C'\fR to make the cache type
unambiguous (and this may be required on systems that use a cache type
other than file as the default).
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and session groups.
.IP "no_ccache" 4
.IX Item "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 \s-1PAM\s0 configuration for a
particular service that uses \s-1PAM\s0 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 \fIpam_authenticate()\fR; other functions like \fIpam_setcred()\fR,
\&\fIpam_start_session()\fR, and \fIpam_acct_mgmt()\fR don't make sense with this
option.  Don't use this option if the application needs \s-1PAM\s0 account and
session management calls.
.Sp
This option is only applicable to the auth group.
.IP "retain_after_close" 4
.IX Item "retain_after_close"
Normally, the user's ticket cache is destroyed when either \fIpam_end()\fR or
\&\fIpam_close_session()\fR 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 \s-1PAM\s0 module will never destroy
the user's ticket cache.  If you set this, you may want to call
\&\fBkdestroy\fR in the shell's logout configuration or run a temporary file
removal program to avoid accumulating hundreds of ticket caches in
\&\fI/tmp\fR.
.Sp
This option can be set in \fIkrb5.conf\fR and is only applicable to the auth
and session groups.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1KRB5CCNAME\s0" 4
.IX Item "KRB5CCNAME"
Set by \fIpam_setcred()\fR with the \s-1PAM_ESTABLISH_CRED\s0 option, and therefore
also by \fIpam_open_session()\fR, to point to the new credential cache for the
user.  See the \fIccache\fR and \fIccache_dir\fR options.  By default, the cache
name will be prefixed with \f(CW\*(C`FILE:\*(C'\fR to make the cache type unambiguous.
.IP "\s-1PAM_KRB5CCNAME\s0" 4
.IX Item "PAM_KRB5CCNAME"
Set by \fIpam_authenticate()\fR to point to the temporary ticket cache used for
authentication (unless the \fIno_ccache\fR option was given).  \fIpam_setcred()\fR
then uses that environment variable to locate the temporary cache even if
it was not called in the same \s-1PAM\s0 session as \fIpam_authenticate()\fR (a problem
with \fBsshd\fR running in some modes).  This environment variable is only
used internal to the \s-1PAM\s0 module.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/tmp/krb5cc_UID_RANDOM\fR" 4
.IX Item "/tmp/krb5cc_UID_RANDOM"
The default credential cache name.  \s-1UID\s0 is the decimal \s-1UID\s0 of the local
user and \s-1RANDOM\s0 is a random six-character string.  The pattern may be
changed with the \fIccache\fR option and the directory with the \fIccache_dir\fR
option.
.IP "\fI/tmp/krb5cc_pam_RANDOM\fR" 4
.IX Item "/tmp/krb5cc_pam_RANDOM"
The credential cache name used for the temporary credential cache created
by \fIpam_authenticate()\fR.  This cache is removed again when the \s-1PAM\s0 session
is ended or when \fIpam_setcred()\fR is called and will normally not be
user-visible.  \s-1RANDOM\s0 is a random six-character string.
.IP "\fI~/.k5login\fR" 4
.IX Item "~/.k5login"
File containing Kerberos principals that are allowed access to that
account.
.SH "BUGS"
.IX Header "BUGS"
If \fItry_pkinit\fR is set and pam\-krb5 is built with \s-1MIT\s0 Kerberos, the
user's password is not saved in the \s-1PAM\s0 data if \s-1PKINIT\s0 fails and the
module falls back to password authentication.
.SH "CAVEATS"
.IX Header "CAVEATS"
Be sure to list this module in the session group as well as the auth group
when using it for interactive logins.  Otherwise, some applications (such
as OpenSSH) will not set up the user's ticket cache correctly.
.PP
The Kerberos library, via pam\-krb5, will prompt the user to change their
password if their password is expired, but when using OpenSSH, this will
only work when ChallengeResponseAuthentication is enabled.  Unless this
option is enabled, OpenSSH doesn't pass \s-1PAM\s0 messages to the user and can
only respond to a simple password prompt.
.PP
If you are using \s-1MIT\s0 Kerberos, be aware that users whose passwords are
expired will not be prompted to change their password unless the \s-1KDC\s0
configuration for your realm in [realms] in krb5.conf contains a
master_kdc setting or, if using \s-1DNS\s0 \s-1SRV\s0 records, you have a \s-1DNS\s0 entry for
_kerberos\-master as well as _kerberos.
.PP
\&\fIpam_authenticate()\fR returns failure when called for an ignored account,
requiring the system administrator to use \f(CW\*(C`optional\*(C'\fR or \f(CW\*(C`sufficient\*(C'\fR to
ignore the module and move on to the next module.  It's arguably more
correct to return \s-1PAM_IGNORE\s0, which causes the module to be ignored as if
it weren't in the configuration, but this increases the risk of
inadvertent security holes when listing pam\-krb5 as the only
authentication module.
.PP
This module treats the empty password as an authentication failure
rather than attempting to use that password to avoid unwanted prompting
behavior in the Kerberos libraries.  If you have a Kerberos principal that
intentionally has an empty password, it won't work with this module.
.PP
This module will not refresh an existing ticket cache if called with an
effective \s-1UID\s0 or \s-1GID\s0 different than the real \s-1UID\s0 or \s-1GID\s0, since refreshing
an existing ticket cache requires trusting the \s-1KRB5CCNAME\s0 environment
variable and the environment should not be trusted in a setuid context.
.PP
Old versions of OpenSSH are known to call pam_authenticate followed by
pam_setcred(\s-1PAM_REINITIALIZE_CRED\s0) without first calling pam_open_session,
thereby requesting that an existing ticket cache be renewed (similar to
what a screensaver would want) rather than requesting a new ticket cache
be created.  Since this behavior is indistinguishable at the \s-1PAM\s0 level
from a screensaver, pam\-krb5 when used with these old versions of OpenSSH
will refresh the ticket cache of the OpenSSH daemon rather than setting up
a new ticket cache for the user.  The resulting ticket cache will have the
correct permissions, but will not be named correctly or referenced in the
user's environment and will be overwritten by the next user login.  The
best solution to this problem is to upgrade OpenSSH.  I'm not sure exactly
when this problem was fixed, but at the very least OpenSSH 4.3 and later
do not exhibit it.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIkadmin\fR\|(8), \fIkdestroy\fR\|(1), \fIkrb5.conf\fR\|(5), \fIpam\fR\|(7), \fIpasswd\fR\|(1), \fIsyslog\fR\|(3)
.PP
The current version of this module is available from its web page at
<http://www.eyrie.org/~eagle/software/pam\-krb5/>.