unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

pam_krb5(5)           Standards, Environments, and Macros          pam_krb5(5)



NAME
       pam_krb5  -  authentication,  account, session, and password management
       PAM modules for Kerberos V5

SYNOPSIS
       /usr/lib/security/pam_krb5.so.1

DESCRIPTION
       The Kerberos V5 service module for PAM provides functionality  for  all
       four  PAM  modules: authentication, account management, session manage-
       ment, and password management. The service 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 Authentication Module
       The Kerberos V5 authentication component provides functions  to  verify
       the  identity  of a user, pam_sm_authenticate(), and to manage the Ker-
       beros credentials cache, pam_sm_setcred().

       pam_sm_authenticate() authenticates a user principal through  the  Ker-
       beros authentication service. If the authentication request is success-
       ful, the authentication service sends a  ticket-granting  ticket  (TGT)
       back  to the service module, which then verifies that the TGT came from
       a valid Key Distribution Center (KDC) by attempting to  get  a  service
       ticket  for  the  local  host  service.  For this to succeed, the local
       host's keytab file (/etc/krb5/krb5.keytab) must contain the  entry  for
       the   local   host  service.   For  example,  in  the  file  host/host-
       name.com@REALM, hostname.com is the fully qualified local hostname  and
       REALM   is   the  default  realm  of  the  local  host  as  defined  in
       /etc/krb5/krb5.conf. If the host entry is not found in the keytab file,
       the  authentication  fails.  Administrators may optionally disable this
       "strict" verification by setting the "verify_ap_req_nofail = false"  in
       /etc/krb5/krb5.conf.  See krb5.conf(4) for more details on this option.
       This allows TGT verification to succeed in the absence of a keytab host
       principal entry.

       pam_sm_authenticate(3PAM) may be passed the following flag:

       PAM_DISALLOW_NULL_AUTHTOK

           This  flag  is  ignored. The Kerberos authentication mechanism will
           not allow an empty password string by default.



       pam_sm_setcred() creates and modifies the user's credential cache. This
       function  initializes  the  user's  credential  cache,  if  it does not
       already exist, and stores the initial credentials for later use by Ker-
       berized  network  applications.  The  following flags may be set in the
       flags field. They are best described by their effect on the user's cre-
       dential cache.

       PAM_ESTABLISH_CRED

           Stores  the  initial  credentials in the user's credential cache so
           that the user may access Kerberos network services. If the  creden-
           tial cache exists, then this function is functionally equivalent to
           using the PAM_REFRESH_CRED flag. That is,  the  user's  credentials
           are  refreshed.  If the credential cache does not exist, then it is
           created, and new credentials are stored in it.



       PAM_DELETE_CRED

           This flag has no effect on the credential cache and always  returns
           PAM_SUCCESS.  The  credential cache is not deleted because there is
           no accurate method to determine if the credentials  are  needed  by
           another  process. The credential cache may be deleted with the kde-
           stroy(1) command.



       PAM_REINITIALIZE_CRED

           Deletes the user's existing credential cache,  if  it  exists,  and
           creates  a  new credential cache. The new credentials are stored in
           the new cache and the user's ticket  lifetime  and  renewable  life
           time values are reset.



       PAM_REFRESH_CRED

           Extends  lifetime of user's credentials. Does not wipe out the cre-
           dentials cache, but instead just extends the lifetime of the user's
           TGT. Notice that this function fails if the user's renewable ticket
           lifetime has expired.



       The following options can be passed to the Kerberos  V5  authentication
       module:

       debug           Provides  syslog(3C) debugging information at LOG_DEBUG
                       level.



       nowarn          Turns off warning messages.



   Kerberos V5 Account Management Module
       The Kerberos account management component provides a function  to  per-
       form  account  management,  pam_sm_acct_mgmt(). This function checks to
       see if the pam_krb5 authentication module has  noted  that  the  user's
       password has not expired. The following options may be passed in to the
       Kerberos V5 account management module:

       debug           Provides syslog(3C) debugging information at  LOG_DEBUG
                       level



       nowarn          Turns  off  warning  messages. Also, does not query KDC
                       for impending password expiration information  used  to
                       warn the user.



   Kerberos V5 Session Management Module
       The Kerberos V5 session management component provides functions to ini-
       tiate pam_sm_open_session() and terminate  pam_sm_close_session()  Ker-
       beros   sessions.   For   Kerberos  V5,  both  pam_sm_open_session  and
       pam_sm_close_session() are null functions, returning PAM_IGNORE.

   Kerberos V5 Password Management Module
       The Kerberos V5 password management component provides  a  function  to
       change  passwords,  pam_sm_chauthtok(),  in the Key Distribution Center
       (KDC) database. The following flags may  be  passed  to  pam_sm_chauth-
       tok(3PAM):

       PAM_CHANGE_EXPIRED_AUTHTOK

           The  password  service should only update the user's Kerberos pass-
           word if it is expired. Otherwise, this function returns PAM_IGNORE.
           The default behaviour is to always change the user's Kerberos pass-
           word.



       PAM_PRELIM_CHECK

           This is a null function that always returns PAM_SUCCESS.



       PAM_UPDATE_AUTHTOK

           This flag is necessary to change the user's Kerberos  password.  If
           this flag is not set, pam_krb5 returns PAM_SYSTEM_ERR.



       The following option can be passed to the Kerberos V5 password module:

       debug           Provides  syslog(3C) debugging information at LOG_DEBUG
                       level.



ERRORS
       The following error codes are returned for pam_sm_authenticate():

       PAM_AUTH_ERR

           Authentication failure



       PAM_BUF_ERR

           Memory buffer error.



       PAM_IGNORE

           The user is "root" and the root key exists in the default keytab.



       PAM_SUCCESS

           Successfully obtained Kerberos credentials .



       PAM_SYSTEM_ERR

           System error.



       PAM_USER_UNKNOWN

           An unknown Kerberos principal was requested.



       The following error codes are returned for pam_sm_setcred():

       PAM_AUTH_ERR

           Authentication failure.



       PAM_BUF_ERR

           Memory buffer error.



       PAM_IGNORE

           The user is "root" and the root key exists in the default keytab.



       PAM_SYSTEM_ERR

           System error.



       PAM_SUCCESS

           Successfully modified the Kerberos credential cache.



       The following error codes are returned for pam_sm_acct_mgmt():

       PAM_AUTH_ERR

           Authentication failure.



       PAM_IGNORE

           Kerberos service module pam_sm_authenticate() was never called,  or
           the user is "root" and the root key exists in the default keytab.



       PAM_NEW_AUTHTOK_REQD

           Obtain new authentication token from the user.



       PAM_SERVICE_ERR

           Error in underlying service module.



       PAM_SUCCESS

           Kerberos principal account is valid.



       PAM_SYSTEM_ERR

           System error.



       PAM_USER_UNKNOWN

           An unknown Kerberos principal was requested.



       The  following  error  code  is  returned for pam_sm_open_session() and
       pam_sm_close_session():

       PAM_IGNORE

           These two functions are null functions in pam_krb5:



       The following error codes are returned for pam_sm_chauthtok():

       PAM_AUTH_ERR

           Authentication failure.



       PAM_IGNORE

           The user has not been  authenticated  by  Kerberos  service  module
           pam_sm_authenticate(),  or  the  user  is  "root"  and the root key
           exists in the default keytab.



       PAM_NEW_AUTHTOK_REQD

           User's Kerberos password has expired.



       PAM_SERVICE_ERR

           Error in module. At least one input parameter is missing.



       PAM_SYSTEM_ERR

           System error.



       PAM_USER_UNKNOWN

           An unknown Kerberos principal was requested.



       PAM_SUCCESS

           Successfully changed the user's Kerberos password.




EXAMPLES
       Example 1: Authenticate Users Through Kerberos as First Choice

       The following is an excerpt of a  sample  pam.conf  configuration  file
       that  authenticates  users  through the Kerberos authentication service
       and authenticates through the Unix login only if the Kerberos authenti-
       cation  fails. This arrangement is helpful when a majority of the users
       are networked by means of Kerberos and when there are only a  few  non-
       Kerberos  type  user  accounts,  such  as root. The service illustrated
       below is for dtlogin.

       dtlogin auth requisite          pam_smartcard.so.1
       dtlogin auth requisite          pam_authtok_get.so.1
       dtlogin auth required           pam_dhkeys.so.1
       dtlogin auth required           pam_unix_cred.so.1
       dtlogin auth sufficient         pam_krb5.so.1
       dtlogin auth required           pam_unix_auth.so.1


       Note that these changes should not be made  to  the  existing  krlogin,
       krsh,  and  ktelnet  service  entries.  Those services require Kerberos
       authentication, so using a seemingly sufficient control flag would  not
       provide  the  necessary  functionality for privacy and integrity. There
       should be no need to change those entries.

       The following entries check for password expiration when  dealing  with
       Kerberos and Unix password aging policies:

       other   account requisite       pam_roles.so.1
       other   account required        pam_unix_account.so.1
       other   account required        pam_krb5.so.1


       The  following  entries  would change the Kerberos password of the user
       and continue to change the Unix login password  only  if  the  Kerberos
       password change had failed:

       other   password required       pam_dhkeys.so.1
       other   password requisite      pam_authtok_get.so.1
       other   password requisite      pam_authtok_check.so.1
       other   password sufficient     pam_krb5.so.1
       other   password required       pam_authtok_store.so.1


       When  changing  Kerberos  based  user's  password, use kpasswd(1). When
       changing a non-Kerberos user's password, it  is  recommended  that  the
       repository is specified (-r) with the passwd(1) command.

       Example 2: Authenticate Users Through Kerberos Only

       The  following  example  allows  authentication only to users that have
       Kerberos-based accounts.

       dtlogin auth requisite          pam_smartcard.so.1
       dtlogin auth requisite          pam_authtok_get.so.1
       dtlogin auth required           pam_dhkeys.so.1
       dtlogin auth required           pam_unix_cred.so.1
       dtlogin auth binding            pam_krb5.so.1
       dtlogin auth required           pam_unix_auth.so.1


       Typically, you would have another service  specified  in  the  pam.conf
       file that would allow local users, such as database, web server, system
       administrator accounts, to log in to the host machine. For example, the
       "login"  service  name  could  be used for these users. Note that these
       users should not belong to any roles.

       The rest of the module types look similar to that shown in the previous
       example:

       other   account requisite       pam_roles.so.1
       other   account required        pam_unix_account.so.1
       other   account required        pam_krb5.so.1


       With  binding specified in the following, it is important that non-Ker-
       beros users specify the repository in which they reside  using  the  -r
       option  with the passwd(1) command. This configuration is also based on
       the assumptions that:

         o  Kerberos users maintain only their Kerberos passwords;

         o  changing their Unix password is not necessary, given that they are
            authenticated  only  through their Kerberos passwords when logging
            in.


       other   password required       pam_dhkeys.so.1
       other   password requisite      pam_authtok_get.so.1
       other   password requisite      pam_authtok_check.so.1
       other   password binding        pam_krb5.so.1
       other   password required       pam_authtok_store.so.1


       Example 3: Authenticate Through Kerberos Optionally

       This configuration is helpful when the majority of users  are  non-Ker-
       beros  users  and  would  like to authenticate through Kerberos if they
       happened to exist in the Kerberos database. The effect of this is simi-
       lar  to  users  voluntarily executing kinit(1) after they have success-
       fully logged in:

       dtlogin auth requisite          pam_smartcard.so.1
       dtlogin auth requisite          pam_authtok_get.so.1
       dtlogin auth required           pam_dhkeys.so.1
       dtlogin auth required           pam_unix_cred.so.1
       dtlogin auth required           pam_unix_auth.so.1
       dtlogin auth optional           pam_krb5.so.1


       The rest of the configuration is as follows:

       other   account requisite       pam_roles.so.1
       other   account required        pam_unix_account.so.1
       other   account required        pam_krb5.so.1

       other   password required       pam_dhkeys.so.1
       other   password requisite      pam_authtok_get.so.1
       other   password requisite      pam_authtok_check.so.1
       other   password required       pam_authtok_store.so.1
       other   password optional       pam_krb5.so.1


       Non-Kerberos users should  specify  their  respective  repositories  by
       using  the  -r  option  when changing their password with the passwd(1)
       command.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityEvolv-
       ing


SEE ALSO
       kdestroy(1),  kinit(1),  kpasswd(1),  passwd(1),  ktkt_warnd(1M),  lib-
       pam(3LIB),     pam(3PAM),     pam_sm(3PAM),     pam_sm_acct_mgmt(3PAM),
       pam_sm_authenticate(3PAM),  pam_sm_chauthtok(3PAM),   pam_sm_close_ses-
       sion(3PAM),   pam_sm_open_session(3PAM),   pam_sm_setcred(3PAM),   sys-
       log(3C), pam.conf(4), attributes(5), krb5envvar(5), SEAM(5)

NOTES
       The interfaces in libpam(3LIB) are MT-Safe only if each  thread  within
       the multi-threaded application uses its own PAM handle.

       On  successful  acquisition  of  initial  credentials  (ticket-granting
       ticket), ktkt_warnd(1M) will be notified, to alert the  user  when  the
       initial credentials are about to expire.



SunOS 5.10                        22 Apr 2004                      pam_krb5(5)