1.\" 2.\" $Id: pam_krb5.5,v 1.5 2000/01/05 00:59:56 fcusack Exp $ 3.\" $FreeBSD$ 4.Dd January 15, 1999 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.El 112.Ss Kerberos 5 Account Management Module 113The Kerberos 5 account management component 114provides a function to perform account management, 115.Fn pam_sm_acct_mgmt . 116The function verifies that the authenticated principal is allowed 117to login to the local user account by calling 118.Fn krb5_kuserok 119(which checks the user's 120.Pa .k5login 121file). 122.Ss Kerberos 5 Password Management Module 123The Kerberos 5 password management component 124provides a function to change passwords 125.Pq Fn pam_sm_chauthtok . 126The username supplied (the 127user running the 128.Xr passwd 1 129command, or the username given as an argument) is mapped into 130a Kerberos principal name, using the same technique as in 131the authentication module. 132Note that if a realm name was 133explicitly supplied during authentication, but not during 134a password change, the mapping 135done by the password management module may not result in the 136same principal as was used for authentication. 137.Pp 138Unlike when 139changing a 140.Ux 141password, the password management module will 142allow any user to change any principal's password (if the user knows 143the principal's old password, of course). 144Also unlike 145.Ux , 146root 147is always prompted for the principal's old password. 148.Pp 149The password management module uses the same heuristics as 150.Xr kpasswd 1 151to determine how to contact the Kerberos password server. 152.Pp 153The following options may be passed to the password management 154module: 155.Bl -tag -width ".Cm use_first_pass" 156.It Cm debug 157.Xr syslog 3 158debugging information at 159.Dv LOG_DEBUG 160level. 161.It Cm use_first_pass 162If the password management module is not the first in the stack, 163and a previous module obtained the user's old password, that password is 164used to authenticate the user. 165If this fails, the password 166management 167module returns failure without prompting the user for the old password. 168If successful, the new password entered to the previous module is also 169used as the new Kerberos password. 170If the new password fails, 171the password management module returns failure without 172prompting the user for a new password. 173.It Cm try_first_pass 174This option is similar to the 175.Cm use_first_pass 176option, except that if the previously obtained old or new passwords fail, 177the user is prompted for them. 178.El 179.Ss Kerberos 5 Session Management Module 180The Kerberos 5 session management component 181provides functions to initiate 182.Pq Fn pam_sm_open_session 183and terminate 184.Pq Fn pam_sm_close_session 185sessions. 186Since session management is not defined under Kerberos 5, 187both of these functions simply return success. 188They are provided 189only because of the naming conventions for PAM modules. 190.Sh ENVIRONMENT 191.Bl -tag -width "KRB5CCNAME" 192.It Ev KRB5CCNAME 193Location of the credentials cache. 194.El 195.Sh FILES 196.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 197.It Pa /tmp/krb5cc_ Ns Ar uid 198default credentials cache 199.Ar ( uid 200is the decimal UID of the user). 201.It Pa $HOME/.k5login 202file containing Kerberos principals that are allowed access. 203.El 204.Sh SEE ALSO 205.Xr kdestroy 1 , 206.Xr passwd 1 , 207.Xr syslog 3 , 208.Xr pam.conf 5 , 209.Xr pam 8 210.Sh NOTES 211Applications should not call 212.Fn pam_authenticate 213more than once between calls to 214.Fn pam_start 215and 216.Fn pam_end 217when using the Kerberos 5 PAM module. 218