Provided by: libpam-krb5_1.2.0-3_i386 bug

NAME

       pam_krb5 - Kerberos 5 PAM module

SYNOPSIS

       auth            sufficient      pam_krb5.so ignore_root
       account         required        pam_krb5.so ignore_root
       password        optional        pam_krb5.so ignore_root
       session         optional        pam_krb5.so ignore_root

DESCRIPTION

       The     Kerberos     5    service    module    for    PAM,    typically
       /lib/security/pam_krb5.so,  provides  functionality   for   three   PAM
       categories: authentication, account management, session management, and
       password management.

       The pam_krb5.so module is a  shared  object  that  can  be  dynamically
       loaded to provide the necessary functionality upon demand.  Its path is
       specified in the PAM configuration file.

Kerberos 5 Authentication Module

       The Kerberos 5 authentication component provides  functions  to  verify
       the  identity  of  a  user.   (pam_sm_authenticate())  and  to set user
       specific   credentials    (pam_sm_setcred()).     pam_sm_authenticate()
       converts  the supplied username into a Kerberos principal, by appending
       the default local realm name.  It also supports usernames with explicit
       realm names.

       It  prompts  the user for a password and obtains a new Kerberos TGT for
       the principal. The TGT is verified by obtaining a  service  ticket  for
       the local host.

       The  pam_sm_setcred() function stores the newly acquired credentials in
       a credentials cache,  and  sets  the  environment  variable  KRB5CCNAME
       appropriately.  This module destroys the credentials cache when the PAM
       data is cleaned up.  Thus, you should  set  close_sessions  to  yes  in
       /etc/login.defs.

       If  the authentication is done as root and a local keytab is available,
       pam_krb5.so will do a  proper  Kerberos  authentication  by  using  the
       Kerberos  TGT acquired to obtain a service ticket and then validate the
       service ticket against a local keytab.  If there is no local keytab  or
       if  the  keytab file (/etc/krb5.keytab) is not readable, this step will
       be skipped.  Without performing this step, authentication is vulnerable
       to  KDC spoofing.  If a keytab is available, the module first looks for
       a principal named host/machine where machine  is  the  fully  qualified
       local  hostname.   If  that  principal  isn’t  available,  it looks for
       service/machine where service  is  the  PAM  service  used  (the  first
       argument to pam_start()) and machine is the same as above.

       The following options may be passed to the authentication module:

       debug          syslog(3) debugging information at LOG_DEBUG level.

       use_first_pass If  the  authentication  module  is not the first in the
                      stack,  and  a  previous  module  obtained  the   user’s
                      password,  that  password  is  used  to authenticate the
                      user.  If this fails, the authentication module  returns
                      failure without prompting the user for a password.  This
                      option has no effect if the authentication module is the
                      first  in  the stack, or if no previous modules obtained
                      the user’s password.

       try_first_pass This option is similar  to  the  use_first_pass  option,
                      except  that  if the previously obtained password fails,
                      the user is prompted for another password.

       forwardable    Obtain forwardable Kerberos credentials for the user.

       no_ccache      Do not save the obtained credentials  in  a  credentials
                      cache.  This  is  a  useful option if the authentication
                      module is used for services such as ftp  or  pop,  where
                      the user would not be able to destroy them. [This is not
                      a recommendation to use the module for those  services.]

       ignore_root    Never  attempt  to authenticate the user "root".  Always
                      fail immediately if that user  is  being  authenticated;
                      presumably  the  PAM  stack will fall back to some other
                      mechanism.

       search_k5login Normally,  the   authentication   module   attempts   to
                      authenticate  as  a  Kerberos principal derived from the
                      username by appending the default  realm.   Verification
                      of the presence of that Kerberos principal in the user’s
                      .k5login  file  can  then  be  done  via   the   account
                      management  module.   When  this  option  is given and a
                      .k5login file  is  present,  the  provided  password  is
                      instead used to attempt to authenticate as each Kerberos
                      principal listed in the .k5login file in turn.  If there
                      is no .k5login file, the behavior is the same as normal.
                      This may be useful when there is no simple mapping  from
                      local  username to Kerberos principal name, but requires
                      the  .k5login  file  be  readable   at   the   time   of
                      authentication  (and therefore may not work with schemes
                      such as sshd’s privilege separation).

Kerberos 5 Session Management Module

       The Kerberos 5  session  management  component  provides  functions  to
       initiate (pam_sm_open_session()) and terminate (pam_sm_close_session())
       sessions.   This  module  takes  all  of  the  same  options   as   the
       authentication  module and will authenticate the user if authentication
       has not already been established.  In addition, it takes the  following
       options specific to this module:

       ccache=<name>
              Use <name> as the credentials cache.  <name> must be in the form
              type:residual (where type is optional if a file cache is  used).
              The special tokens %u, to designate the decimal uid of the user,
              and %p, to designate the current process  id,  can  be  used  in
              <name>.   If  <name>  ends  with  the literal string XXXXXX (six
              X’s),  that  string  will  be  replaced  by  randomly  generated
              characters  and  the  ticket  cache opened via mkstemp.  This is
              strongly  recommended  if  <name>  points  to  a  world-writable
              directory.

       ccache_dir=<dir>
              Put  the  ticket  cache in <dir> instead of the default of /tmp.
              Ignored if ccache is also set.

Kerberos 5 Account Management Module

       The Kerberos 5 account management  component  provides  a  function  to
       perform  account management, pam_sm_acct_mgmt().  The function verifies
       that the authenticated principal is allowed to login to the local  user
       account  by  calling  krb5_kuserok()  (which checks the user’s .k5login
       file).  Note that  this  is  also  done  by  pam_sm_authenticate()  and
       pam_sm_setcred().

       If  the user didn’t log on using krb5, this function silently succeeds.

       The following options may be passed to the account module:

       ignore_root    Skip any attempt to validate the root account  and  just
                      succeed  quietly.   Presumably  whatever  validation  is
                      necessary will be handled by another module in  the  PAM
                      stack.

Kerberos 5 Password Management Module

       The  Kerberos  5  password  management component provides a function to
       change passwords (pam_sm_chauthtok()). The username supplied (the  user
       running the passwd(1) command, or the username given as an argument) is
       mapped into a Kerberos principal name, using the same technique  as  in
       the  authentication  module.   Note that if a realm name was explicitly
       supplied during authentication, but not during a password  change,  the
       mapping  done  by  the password management module may not result in the
       same principal as was used for authentication.

       Unlike when changing a unix password, the  password  management  module
       will  allow  any  user  to change any principal’s password (if the user
       knows the principal’s old password, of course).  Also unlike unix, root
       is always prompted for the principal’s old password.

       The  password  management module uses the same heuristics as kpasswd(1)
       to determine how to contact the Kerberos password server.

       The following options may be passed to the password management module:

       debug          syslog(3) debugging information at LOG_DEBUG level.

       use_first_pass If the password management module is not  the  first  in
                      the stack, and a previous module obtained the user’s old
                      password, that password  is  used  to  authenticate  the
                      user.   If  this  fails,  the password management module
                      returns failure without prompting the user for  the  old
                      password.   If  successful,  the new password entered to
                      the previous module is also used  as  the  new  Kerberos
                      password.   If  the  new  password  fails,  the password
                      management module returns failure without prompting  the
                      user for a new password.

       try_first_pass This  option  is  similar  to the use_first_pass option,
                      except that  if  the  previously  obtained  old  or  new
                      passwords fail, the user is prompted for them.

       ignore_root    Do  not  try to change passwords for the root user, just
                      fail immediately.

ENVIRONMENT

       KRB5CCNAME      Location of the credentials cache.

FILES

       /tmp/krb5cc_[uid]_[rand]
              default credentials cache ([uid] is the decimal UID of the  user
              and  [rand]  is  a random string).  The directory in which it is
              stored may be changed with the ccache_dir option.

       ~/.k5login
              file containing Kerberos principals that are allowed access.

SEE ALSO

       kdestroy(1), passwd(1), pam(7), syslog(3).

NOTES

       Applications should not call pam_authenticate() more than once  between
       calls  to  pam_start()  and  pam_end()  when  using  the Kerberos 5 PAM
       module.