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