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