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