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 allow_kdc_spoof 112Allow 113.Nm 114to succeed even if there is no host or service key available in a 115keytab to authenticate the Kerberos KDC's ticket. 116If there is no such key, for example on a host with no keytabs, 117.Nm 118will fail immediately without prompting the user. 119.Pp 120.Sy Warning : 121If the host has not been configured with a keytab from the KDC, setting 122this option makes it vulnerable to malicious KDCs, e.g. via DNS 123flooding, because 124.Nm 125has no way to distinguish the legitimate KDC from a spoofed KDC. 126.It Cm no_user_check 127Do not verify if a user exists on the local system. This option implies the 128.Cm no_ccache 129option because there is no secure local uid/gid for the cache file. 130.El 131.Ss Kerberos 5 Account Management Module 132The Kerberos 5 account management component 133provides a function to perform account management, 134.Fn pam_sm_acct_mgmt . 135The function verifies that the authenticated principal is allowed 136to login to the local user account by calling 137.Fn krb5_kuserok 138(which checks the user's 139.Pa .k5login 140file). 141.Ss Kerberos 5 Password Management Module 142The Kerberos 5 password management component 143provides a function to change passwords 144.Pq Fn pam_sm_chauthtok . 145The username supplied (the 146user running the 147.Xr passwd 1 148command, or the username given as an argument) is mapped into 149a Kerberos principal name, using the same technique as in 150the authentication module. 151Note that if a realm name was 152explicitly supplied during authentication, but not during 153a password change, the mapping 154done by the password management module may not result in the 155same principal as was used for authentication. 156.Pp 157Unlike when 158changing a 159.Ux 160password, the password management module will 161allow any user to change any principal's password (if the user knows 162the principal's old password, of course). 163Also unlike 164.Ux , 165root 166is always prompted for the principal's old password. 167.Pp 168The password management module uses the same heuristics as 169.Xr kpasswd 1 170to determine how to contact the Kerberos password server. 171.Pp 172The following options may be passed to the password management 173module: 174.Bl -tag -width ".Cm use_first_pass" 175.It Cm debug 176.Xr syslog 3 177debugging information at 178.Dv LOG_DEBUG 179level. 180.It Cm use_first_pass 181If the password management module is not the first in the stack, 182and a previous module obtained the user's old password, that password is 183used to authenticate the user. 184If this fails, the password 185management 186module returns failure without prompting the user for the old password. 187If successful, the new password entered to the previous module is also 188used as the new Kerberos password. 189If the new password fails, 190the password management module returns failure without 191prompting the user for a new password. 192.It Cm try_first_pass 193This option is similar to the 194.Cm use_first_pass 195option, except that if the previously obtained old or new passwords fail, 196the user is prompted for them. 197.El 198.Ss Kerberos 5 Session Management Module 199The Kerberos 5 session management component 200provides functions to initiate 201.Pq Fn pam_sm_open_session 202and terminate 203.Pq Fn pam_sm_close_session 204sessions. 205Since session management is not defined under Kerberos 5, 206both of these functions simply return success. 207They are provided 208only because of the naming conventions for PAM modules. 209.Sh ENVIRONMENT 210.Bl -tag -width "KRB5CCNAME" 211.It Ev KRB5CCNAME 212Location of the credentials cache. 213.El 214.Sh FILES 215.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 216.It Pa /tmp/krb5cc_ Ns Ar uid 217default credentials cache 218.Ar ( uid 219is the decimal UID of the user). 220.It Pa $HOME/.k5login 221file containing Kerberos principals that are allowed access. 222.El 223.Sh SEE ALSO 224.Xr kdestroy 1 , 225.Xr passwd 1 , 226.Xr syslog 3 , 227.Xr pam.conf 5 , 228.Xr pam 3 229.Sh NOTES 230Applications should not call 231.Fn pam_authenticate 232more than once between calls to 233.Fn pam_start 234and 235.Fn pam_end 236when using the Kerberos 5 PAM module. 237