lib/libpam/modules/pam_krb5/pam_krb5.8

   1 .\"
   2 .\" $Id: pam_krb5.5,v 1.5 2000/01/05 00:59:56 fcusack Exp $
   3 .\" $FreeBSD$
   4 .Dd May 3, 2010
   5 .Dt PAM_KRB5 8
   6 .Os
   7 .Sh NAME
   8 .Nm pam_krb5
   9 .Nd Kerberos 5 PAM module
  10 .Sh SYNOPSIS
  11 .Pa /usr/lib/pam_krb5.so
  12 .Sh DESCRIPTION
  13 The Kerberos 5 service module for PAM, typically
  14 .Pa /usr/lib/pam_krb5.so ,
  15 provides functionality for three PAM categories:
  16 authentication,
  17 account management,
  18 and password management.
  19 It also provides null functions for session management.
  20 The
  21 .Pa pam_krb5.so
  22 module is a shared object
  23 that can be dynamically loaded to provide
  24 the necessary functionality upon demand.
  25 Its path is specified in the
  26 PAM configuration file.
  27 .Ss Kerberos 5 Authentication Module
  28 The Kerberos 5 authentication component
  29 provides functions to verify the identity of a user
  30 .Pq Fn pam_sm_authenticate
  31 and to set user specific credentials
  32 .Pq Fn pam_sm_setcred .
  33 .Fn pam_sm_authenticate
  34 converts the supplied username into a Kerberos principal,
  35 by appending the default local realm name.
  36 It also supports usernames with explicit realm names.
  37 If a realm name is supplied, then upon a successful return, it
  38 changes the username by mapping the principal name into a local username
  39 (calling
  40 .Fn krb5_aname_to_localname ) .
  41 This typically just means
  42 the realm name is stripped.
  43 .Pp
  44 It prompts the user for a password and obtains a new Kerberos TGT for
  45 the principal.
  46 The TGT is verified by obtaining a service
  47 ticket for the local host.
  48 .Pp
  49 When prompting for the current password, the authentication
  50 module will use the prompt
  51 .Dq Li "Password for <principal>:" .
  52 .Pp
  53 The
  54 .Fn pam_sm_setcred
  55 function stores the newly acquired credentials in a credentials cache,
  56 and sets the environment variable
  57 .Ev KRB5CCNAME
  58 appropriately.
  59 The credentials cache should be destroyed by the user at logout with
  60 .Xr kdestroy 1 .
  61 .Pp
  62 The following options may be passed to the authentication module:
  63 .Bl -tag -width ".Cm use_first_pass"
  64 .It Cm debug
  65 .Xr syslog 3
  66 debugging information at
  67 .Dv LOG_DEBUG
  68 level.
  69 .It Cm no_warn
  70 suppress warning messages to the user.
  71 These messages include
  72 reasons why the user's
  73 authentication attempt was declined.
  74 .It Cm use_first_pass
  75 If the authentication module is not the first in the stack,
  76 and a previous module obtained the user's password, that password is
  77 used to authenticate the user.
  78 If this fails, the authentication
  79 module returns failure without prompting the user for a password.
  80 This option has no effect if the authentication module is
  81 the first in the stack, or if no previous modules obtained the
  82 user's password.
  83 .It Cm try_first_pass
  84 This option is similar to the
  85 .Cm use_first_pass
  86 option, except that if the previously obtained password fails, the
  87 user is prompted for another password.
  88 .It Cm forwardable
  89 Obtain forwardable Kerberos credentials for the user.
  90 .It Cm no_ccache
  91 Do not save the obtained credentials in a credentials cache.
  92 This is a
  93 useful option if the authentication module is used for services such
  94 as ftp or pop, where the user would not be able to destroy them.
  95 [This
  96 is not a recommendation to use the module for those services.]
  97 .It Cm ccache Ns = Ns Ar name
  98 Use
  99 .Ar name
 100 as the credentials cache.
 101 .Ar name
 102 must be in the form
 103 .Ar type : Ns Ar residual .
 104 The special tokens
 105 .Ql %u ,
 106 to designate the decimal UID of the user;
 107 and
 108 .Ql %p ,
 109 to designate the current process ID; can be used in
 110 .Ar name .
 111 .It Cm no_user_check
 112 Do not verify if a user exists on the local system. This option implies the
 113 .Cm no_ccache
 114 option because there is no secure local uid/gid for the cache file.
 115 .El
 116 .Ss Kerberos 5 Account Management Module
 117 The Kerberos 5 account management component
 118 provides a function to perform account management,
 119 .Fn pam_sm_acct_mgmt .
 120 The function verifies that the authenticated principal is allowed
 121 to login to the local user account by calling
 122 .Fn krb5_kuserok
 123 (which checks the user's
 124 .Pa .k5login
 125 file).
 126 .Ss Kerberos 5 Password Management Module
 127 The Kerberos 5 password management component
 128 provides a function to change passwords
 129 .Pq Fn pam_sm_chauthtok .
 130 The username supplied (the
 131 user running the
 132 .Xr passwd 1
 133 command, or the username given as an argument) is mapped into
 134 a Kerberos principal name, using the same technique as in
 135 the authentication module.
 136 Note that if a realm name was
 137 explicitly supplied during authentication, but not during
 138 a password change, the mapping
 139 done by the password management module may not result in the
 140 same principal as was used for authentication.
 141 .Pp
 142 Unlike when
 143 changing a
 144 .Ux
 145 password, the password management module will
 146 allow any user to change any principal's password (if the user knows
 147 the principal's old password, of course).
 148 Also unlike
 149 .Ux ,
 150 root
 151 is always prompted for the principal's old password.
 152 .Pp
 153 The password management module uses the same heuristics as
 154 .Xr kpasswd 1
 155 to determine how to contact the Kerberos password server.
 156 .Pp
 157 The following options may be passed to the password management
 158 module:
 159 .Bl -tag -width ".Cm use_first_pass"
 160 .It Cm debug
 161 .Xr syslog 3
 162 debugging information at
 163 .Dv LOG_DEBUG
 164 level.
 165 .It Cm use_first_pass
 166 If the password management module is not the first in the stack,
 167 and a previous module obtained the user's old password, that password is
 168 used to authenticate the user.
 169 If this fails, the password
 170 management
 171 module returns failure without prompting the user for the old password.
 172 If successful, the new password entered to the previous module is also
 173 used as the new Kerberos password.
 174 If the new password fails,
 175 the password management module returns failure without
 176 prompting the user for a new password.
 177 .It Cm try_first_pass
 178 This option is similar to the
 179 .Cm use_first_pass
 180 option, except that if the previously obtained old or new passwords fail,
 181 the user is prompted for them.
 182 .El
 183 .Ss Kerberos 5 Session Management Module
 184 The Kerberos 5 session management component
 185 provides functions to initiate
 186 .Pq Fn pam_sm_open_session
 187 and terminate
 188 .Pq Fn pam_sm_close_session
 189 sessions.
 190 Since session management is not defined under Kerberos 5,
 191 both of these functions simply return success.
 192 They are provided
 193 only because of the naming conventions for PAM modules.
 194 .Sh ENVIRONMENT
 195 .Bl -tag -width "KRB5CCNAME"
 196 .It Ev KRB5CCNAME
 197 Location of the credentials cache.
 198 .El
 199 .Sh FILES
 200 .Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact
 201 .It Pa /tmp/krb5cc_ Ns Ar uid
 202 default credentials cache
 203 .Ar ( uid
 204 is the decimal UID of the user).
 205 .It Pa $HOME/.k5login
 206 file containing Kerberos principals that are allowed access.
 207 .El
 208 .Sh SEE ALSO
 209 .Xr kdestroy 1 ,
 210 .Xr passwd 1 ,
 211 .Xr syslog 3 ,
 212 .Xr pam.conf 5 ,
 213 .Xr pam 8
 214 .Sh NOTES
 215 Applications should not call
 216 .Fn pam_authenticate
 217 more than once between calls to
 218 .Fn pam_start
 219 and
 220 .Fn pam_end
 221 when using the Kerberos 5 PAM module.