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 sucessful 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 -xwidth ".Cm use_first_pass" 64.It Cm debug 65.Xr syslog 3 66debugging information at 67.Dv LOG_DEBUG 68level. 69.It Cm use_first_pass 70If the authentication module is not the first in the stack, 71and a previous module obtained the user's password, that password is 72used to authenticate the user. 73If this fails, the authentication 74module returns failure without prompting the user for a password. 75This option has no effect if the authentication module is 76the first in the stack, or if no previous modules obtained the 77user's password. 78.It Cm try_first_pass 79This option is similar to the 80.Cm use_first_pass 81option, except that if the previously obtained password fails, the 82user is prompted for another password. 83.It Cm forwardable 84Obtain forwardable Kerberos credentials for the user. 85.It Cm no_ccache 86Do not save the obtained credentials in a credentials cache. 87This is a 88useful option if the authentication module is used for services such 89as ftp or pop, where the user would not be able to destroy them. 90[This 91is not a recommendation to use the module for those services.] 92.It Cm ccache Ns = Ns Ar name 93Use 94.Ar name 95as the credentials cache. 96.Ar name 97must be in the form 98.Ar type : Ns Ar residual . 99The special tokens 100.Ql %u , 101to designate the decimal UID of the user; 102and 103.Ql %p , 104to designate the current process ID; can be used in 105.Ar name . 106.El 107.Ss Kerberos 5 Account Management Module 108The Kerberos 5 account management component 109provides a function to perform account management, 110.Fn pam_sm_acct_mgmt . 111The function verifies that the authenticated principal is allowed 112to login to the local user account by calling 113.Fn krb5_kuserok 114(which checks the user's 115.Pa .k5login 116file). 117.Ss Kerberos 5 Password Management Module 118The Kerberos 5 password management component 119provides a function to change passwords 120.Pq Fn pam_sm_chauthtok . 121The username supplied (the 122user running the 123.Xr passwd 1 124command, or the username given as an argument) is mapped into 125a Kerberos principal name, using the same technique as in 126the authentication module. 127Note that if a realm name was 128explicitly supplied during authentication, but not during 129a password change, the mapping 130done by the password management module may not result in the 131same principal as was used for authentication. 132.Pp 133Unlike when 134changing a 135.Ux 136password, the password management module will 137allow any user to change any principal's password (if the user knows 138the principal's old password, of course). 139Also unlike 140.Ux , 141root 142is always prompted for the principal's old password. 143.Pp 144The password management module uses the same heuristics as 145.Xr kpasswd 1 146to determine how to contact the Kerberos password server. 147.Pp 148The following options may be passed to the password management 149module: 150.Bl -tag -xwidth ".Cm use_first_pass" 151.It Cm debug 152.Xr syslog 3 153debugging information at 154.Dv LOG_DEBUG 155level. 156.It Cm use_first_pass 157If the password management module is not the first in the stack, 158and a previous module obtained the user's old password, that password is 159used to authenticate the user. 160If this fails, the password 161management 162module returns failure without prompting the user for the old password. 163If successful, the new password entered to the previous module is also 164used as the new Kerberos password. 165If the new password fails, 166the password management module returns failure without 167prompting the user for a new password. 168.It Cm try_first_pass 169This option is similar to the 170.Cm use_first_pass 171option, except that if the previously obtained old or new passwords fail, 172the user is prompted for them. 173.El 174.Ss Kerberos 5 Session Management Module 175The Kerberos 5 session management component 176provides functions to initiate 177.Pq Fn pam_sm_open_session 178and terminate 179.Pq Fn pam_sm_close_session 180sessions. 181Since session management is not defined under Kerberos 5, 182both of these functions simply return success. 183They are provided 184only because of the naming conventions for PAM modules. 185.Sh ENVIRONMENT 186.Bl -tag -width "KRB5CCNAME" 187.It Ev KRB5CCNAME 188Location of the credentials cache. 189.El 190.Sh FILES 191.Bl -tag -xwidth ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 192.It Pa /tmp/krb5cc_ Ns Ar uid 193default credentials cache 194.Ar ( uid 195is the decimal UID of the user). 196.It Pa $HOME/.k5login 197file containing Kerberos principals that are allowed access. 198.El 199.Sh SEE ALSO 200.Xr kdestroy 1 , 201.Xr passwd 1 , 202.Xr syslog 3 , 203.Xr pam.conf 5 , 204.Xr pam 8 205.Sh NOTES 206Applications should not call 207.Fn pam_authenticate 208more than once between calls to 209.Fn pam_start 210and 211.Fn pam_end 212when using the Kerberos 5 PAM module. 213