Provided by: libpam-heimdal_4.5-3_amd64 bug

NAME

       pam_krb5 - Kerberos 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 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 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 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.  All options must be followed by an equal sign (=) and a value, so
       for boolean options add "= true".  The Kerberos 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 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 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 both the temporary ticket cache used during authentication and 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).

           Be aware that pam_krb5 creates and stores a temporary ticket cache file owned by root
           during the login process.  If you set ccache above to avoid using the system /tmp
           directory for user ticket caches, you may also want to set ccache_dir to move those
           temporary caches to some other location.  This will allow pam_krb5 to continue working
           even if the system /tmp directory is full.

           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/ <http://www.eyrie.org/~eagle/software/pam-
       krb5/>.