Provided by: libpam-heimdal_4.4-1ubuntu1_i386 bug

NAME

       pam_krb5 - Kerberos v5 PAM module

SYNOPSIS

         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

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 persistent 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.  You
           can point the Kerberos PAM module at a different keytab with the
           keytab 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 "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.

           If the username provided to PAM contains an "@" and Kerberos can,
           treating the username as a principal, map it to a local account
           name, pam_authenticate() will change the PAM 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 PAM
           module.  Also be aware that several other common PAM modules, such
           as pam_securetty, expect to be able to look up the user with
           getpwnam() and cannot be called before pam_krb5 if this feature is
           used.

           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 return PAM_IGNORE if called in the context of a PAM session
       for a user who did not authenticate with Kerberos (a return code of
       "ignore" in the Linux PAM configuration language).

       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 1000, and set
       ignore_k5login only if the realm is EXAMPLE.COM.

           [appdefaults]
               forwardable = true
               pam = {
                   minimum_uid = 1000
                   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.

   Authorization
       alt_auth_map=<format>
           This functions similarly to the search_k5login option.  The
           <format> argument is used as the authentication Kerberos principal,
           with any %s in <format> replaced with the username.  If the
           username contains an "@", only the part of the username before the
           realm is used to replace %s and the realm is appended to the
           result.  There is no quote removal.

           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 sudo.
           Most examples will look like:

               alt_auth_map=%s/root

           which attempts authentication as the root instance of the username
           first and then falls back to the regular username (but see
           force_alt_auth and only_alt_auth).

           This option can be set in krb5.conf, although normally it doesn't
           make sense to do that; normally it is used in the PAM 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.

       force_alt_auth
           This option is used with alt_auth_map and forces authentication as
           the mapped principal if that principal exists in the KDC.  Only if
           the KDC returns principal unknown does the Kerberos PAM module fall
           back to normal authentication.  This can be used to force
           authentication with an alternate instance.  If alt_auth_map is not
           set, it has no effect.

           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 return
           PAM_IGNORE, telling the PAM library to proceed as if they weren't
           mentioned in the PAM configuration.  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 return
           PAM_IGNORE, telling the PAM library to proceed as if they weren't
           mentioned in the PAM configuration.

           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.

           This option can be set in krb5.conf.

       only_alt_auth
           This option is used with alt_auth_map and forces the use of the
           mapped principal for authentication.  It disables fallback to
           normal authentication in all cases and overrides search_k5login and
           force_alt_auth.  If alt_auth_map is not set, it has no effect and
           the standard authentication behavior is used.

           This option can be set in krb5.conf and is only applicable to the
           auth group.

       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.

   Kerberos Behavior
       fast_ccache=<ccache_name>
           Attempt to use Flexible Authenticatin Secure Tunneling (FAST) to
           protect the authentication.  FAST is a mechanism to protect
           Kerberos against password guessing attacks and provide other
           security improvements.  To work, FAST 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.

           If <ccache_name> names a ticket cache that is readable by the
           authenticating process and has tickets then FAST will be attempted.
           The easiest way to use this option is to use a program like k5start
           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).

           If no credentials are present in the ticket cache, or if the ticket
           cache does not exist or is not readable, FAST will not used and
           authentication will proceed as normal.  However, if the credentials
           in that ticket cache are expired, authentication will fail if the
           KDC supports FAST.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       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.

       keytab=<path>
           Specifies the keytab to use when validating the user's credentials.
           The default is the default system keytab (normally
           /etc/krb5.keytab), which is usually only readable by root.
           Applications not running as root that use this PAM 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.

           This option can be set in krb5.conf and 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.

       ticket_lifetime=<lifetime>
           Obtain tickets with a maximum 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.

   PAM Behavior
       clear_on_fail
           When changing passwords, PAM 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 PAM modules in the stack will
           still be called even if the failing module is marked required or
           requisite.  When using multiple password PAM modules to synchronize
           passwords between multiple systems when they change, this behavior
           can cause unwanted differences between the environments.

           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 KDC, for example), this module will clear the stored password
           in the PAM 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 PAM module
           will not meddle with the stored password if it skips the user due
           to configuration such as minimum_uid.

           Unfortunately, setting this option interferes with other desirable
           PAM 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.

           This option can be set in krb5.conf and is only applicable to the
           password group.

       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.

       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, pam_authenticate() returns an error.

           According to the PAM standard, this is not the correct way to
           handle expired passwords.  Instead, pam_authenticate() should
           return success without attempting a password change, and then
           pam_acct_mgmt() should return PAM_NEW_AUTHTOK_REQD, at which point
           the calling application is responsible for either rejecting the
           authentication or calling pam_chauthtok().  However, following the
           standard requires that all applications call pam_acct_mgmt() and
           check its return status; otherwise, expired accounts may be able to
           successfully authenticate.  Many applications do not do this.

           If this option is set, pam-krb5 uses the fully correct PAM
           mechanism for handling expired accounts instead of failing in
           pam_authenticate().  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 pam_acct_mgmt() and check its
           return status properly.

           This option can be set in krb5.conf and is only applicable to the
           auth group.

       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 defer_pwchange and force_pwchange.

           This option can be set in krb5.conf and is only applicable to the
           auth group.

       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.

           This option can be set in krb5.conf and is only applicable to the
           auth group.

   PKINIT
       pkinit_anchors=<anchors>
           When doing PKINIT 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
           try_pkinit or use_pkinit are set.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       pkinit_prompt
           Before attempting PKINIT authentication, prompt the user to insert
           a smart card.  You may want to set this option for programs such as
           gnome-screensaver that call PAM 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
           try_pkinit 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 try_pkinit or use_pkinit are set.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       pkinit_user=<userid>
           When doing PKINIT authentication, use <userid> as the user ID.  The
           value of this string is highly dependent on the type of PKINIT
           implementation you're using, but will generally be something like:

               PKCS11:/usr/lib/pkcs11/lib/soft-pkcs11.so

           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 try_pkinit or use_pkinit are set.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       preauth_opt=<option>
           Sets a preauth option (currently only applicable when built with
           MIT Kerberos).  <option> is either a key/value pair with the key
           separated from the value by "=" or a boolean option (in which case
           it's turned on).  In krb5.conf, multiple options should be
           separated by whitespace.  In the PAM configuration, this option can
           be given multiple times to set multiple options.  In either case,
           <option> may not contain whitespace.

           The primary use of this option, at least in the near future, will
           be to set options for the MIT Kerberos PKINIT support.  For the
           full list of possible options, see the PKINIT plugin documentation.
           At the time of this writing, "X509_user_identity" is equivalent to
           pkinit_user and "X509_anchors" is equivalent to pkinit_anchors.
           "flag_DSA_PROTOCOL" can only be set via this option.

           Any settings made with this option are applied after the
           pkinit_anchors and pkinit_user options, so if an equivalent setting
           is made via preauth_opt, it will probably override the other
           setting.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.  Note that there is no way to remove a
           setting made in krb5.conf using the PAM configuration, but options
           set in the PAM configuration are applied after options set in
           krb5.conf and therefore may override earlier settings.

       try_pkinit
           Attempt PKINIT authentication before trying a regular password.
           You will probably also need to set the pkinit_user configuration
           option.  If PKINIT fails, the PAM 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 MIT
           Kerberos 1.6.3 or later.

           If this option is set and pam-krb5 is built against MIT Kerberos,
           and PKINIT fails and the module falls back to password
           authentication, the user's password will not be stored in the PAM
           stack for subsequent modules.  This is a bug in the interaction
           between the module and MIT Kerberos that requires some
           rearchitecting of the PKINIT authentication method to fix.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       use_pkinit
           Require PKINIT authentication.  You will probably also need to set
           the pkinit_user configuration option.  If PKINIT fails,
           authentication will fail.  This option is currently only supported
           if pam-krb5 was built against Heimdal 0.8rc1 or later.  MIT
           Kerberos doesn't provide a method to enforce use of PKINIT, so
           try_pkinit must be used with that implementation instead.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

   Prompting
       banner=<banner>
           By default, the prompts when a user changes their password are:

               Current Kerberos password:
               Enter new Kerberos password:
               Retype new Kerberos password:

           The string "Kerberos" is inserted so that users aren't confused
           about which password they're changing.  Setting this option
           replaces the word "Kerberos" with whatever this option is set to.
           Setting this option to the empty string removes the word before
           "password:" entirely.

           If set in the PAM configuration, <banner> may not contain
           whitespace.  If you want a value containing whitespace, set it in
           krb5.conf.

           This option can be set in krb5.conf and is only applicable to the
           password group.

       expose_account
           By default, the Kerberos PAM module password prompt is simply
           "Password:".  This avoids leaking any information about the system
           realm or account to principal conversions.  If this option is set,
           the string "for <principal>" 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.

           Enabling this option with ChallengeResponseAuthentication enabled
           in OpenSSH may cause problems for some ssh clients that only
           recognize "Password:" as a prompt.  This option is automatically
           disabled if search_k5login is enabled since the principal displayed
           would be inaccurate.

           This option can be set in krb5.conf and is only applicable to the
           auth and password groups.

       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 try_first_pass and use_first_pass for
           weaker versions of this option.

           This option is only applicable to the auth and password groups.
           For the password group, it applies only to the old password.  See
           use_authtok for a similar setting for the new password.

       prompt_principal
           Before prompting for the user's password (or using the previously
           entered password, if try_first_pass, use_first_pass, or
           force_first_pass 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 .k5login file or
           local Kerberos principal to account mapping authorize that
           principal to access the local account.

           Be cautious when using this configuration option and don't use it
           with OpenSSH PasswordAuthentication, only
           ChallengeResponseAuthentication.  Some PAM-enabled applications
           expect PAM 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.

       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 use_first_pass and force_first_pass for
           stronger versions of this option.

           This option is only applicable to the auth and password groups.
           For the password group, it applies only to the old password.

       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
           pam_cracklib.

           This option is only applicable to the password group.

       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 try_first_pass and force_first_pass
           for other versions of this option.

           This option is only applicable to the auth and password groups.
           For the password group, it applies only to the old password.  See
           use_authtok for a similar setting for the new password.

   Ticket Caches
       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.  <directory> may be prefixed with "FILE:" to make the
           cache type unambiguous (and this may be required on systems that
           use a cache type other than file as the default).

           This option can be set in krb5.conf and is only applicable to the
           auth and session groups.

       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(),
           pam_start_session(), and pam_acct_mgmt() don't make sense with this
           option.  Don't use this option if the application needs PAM account
           and session management calls.

           This option 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.

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.  By default, the cache name will be prefixed with "FILE:"
           to make the cache type unambiguous.

       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.

BUGS

       If try_pkinit is set and pam-krb5 is built with MIT Kerberos, the
       user's password is not saved in the PAM data if PKINIT fails and the
       module falls back to password authentication.

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.

       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 PAM messages to the
       user and can only respond to a simple password prompt.

       If you are using MIT Kerberos, be aware that users whose passwords are
       expired will not be prompted to change their password unless the KDC
       configuration for your realm in [realms] in krb5.conf contains a
       master_kdc setting or, if using DNS SRV records, you have a DNS entry
       for _kerberos-master as well as _kerberos.

       pam_authenticate() returns failure when called for an ignored account,
       requiring the system administrator to use "optional" or "sufficient" to
       ignore the module and move on to the next module.  It's arguably more
       correct to return PAM_IGNORE, 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.

       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.

       This module will not refresh an existing ticket cache if called with an
       effective UID or GID different than the real UID or GID, since
       refreshing an existing ticket cache requires trusting the KRB5CCNAME
       environment variable and the environment should not be trusted in a
       setuid context.

       Old versions of OpenSSH are known to call pam_authenticate followed by
       pam_setcred(PAM_REINITIALIZE_CRED) 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 PAM 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.

SEE ALSO

       kadmin(8), kdestroy(1), krb5.conf(5), pam(7), passwd(1), syslog(3)

       The current version of this module is available from its web page at
       <http://www.eyrie.org/~eagle/software/pam-krb5/>.