184d6cd8eSMark Murray.\" 284d6cd8eSMark Murray.\" $Id: pam_krb5.5,v 1.5 2000/01/05 00:59:56 fcusack Exp $ 384d6cd8eSMark Murray.\" $FreeBSD$ 48b136a6dSChris Costello.Dd January 15, 1999 588de1238SRuslan Ermilov.Dt PAM_KRB5 8 688de1238SRuslan Ermilov.Os 78b136a6dSChris Costello.Sh NAME 88b136a6dSChris Costello.Nm pam_krb5 98b136a6dSChris Costello.Nd Kerberos 5 PAM module 108b136a6dSChris Costello.Sh SYNOPSIS 118b136a6dSChris Costello.Pa /usr/lib/pam_krb5.so 128b136a6dSChris Costello.Sh DESCRIPTION 1384d6cd8eSMark MurrayThe Kerberos 5 service module for PAM, typically 148b136a6dSChris Costello.Pa /usr/lib/pam_krb5.so , 1584d6cd8eSMark Murrayprovides functionality for three PAM categories: 1684d6cd8eSMark Murrayauthentication, 1784d6cd8eSMark Murrayaccount management, 1884d6cd8eSMark Murrayand password management. 1984d6cd8eSMark MurrayIt also provides null functions for session management. 2084d6cd8eSMark MurrayThe 218b136a6dSChris Costello.Pa pam_krb5.so 2284d6cd8eSMark Murraymodule is a shared object 2384d6cd8eSMark Murraythat can be dynamically loaded to provide 2484d6cd8eSMark Murraythe necessary functionality upon demand. 2584d6cd8eSMark MurrayIts path is specified in the 268b136a6dSChris CostelloPAM configuration file. 278b136a6dSChris Costello.Ss Kerberos 5 Authentication Module 2884d6cd8eSMark MurrayThe Kerberos 5 authentication component 298b136a6dSChris Costelloprovides functions to verify the identity of a user 308b136a6dSChris Costello.Pq Fn pam_sm_authenticate 3184d6cd8eSMark Murrayand to set user specific credentials 328b136a6dSChris Costello.Pq Fn pam_sm_setcred . 338b136a6dSChris Costello.Fn pam_sm_authenticate 3484d6cd8eSMark Murrayconverts the supplied username into a Kerberos principal, 3584d6cd8eSMark Murrayby appending the default local realm name. 3684d6cd8eSMark MurrayIt also supports usernames with explicit realm names. 37a48060a2SDima DorfmanIf a realm name is supplied, then upon a successful return, it 3884d6cd8eSMark Murraychanges the username by mapping the principal name into a local username 398b136a6dSChris Costello(calling 4088de1238SRuslan Ermilov.Fn krb5_aname_to_localname ) . 418b136a6dSChris CostelloThis typically just means 4284d6cd8eSMark Murraythe realm name is stripped. 438b136a6dSChris Costello.Pp 4484d6cd8eSMark MurrayIt prompts the user for a password and obtains a new Kerberos TGT for 4588de1238SRuslan Ermilovthe principal. 4688de1238SRuslan ErmilovThe TGT is verified by obtaining a service 4784d6cd8eSMark Murrayticket for the local host. 488b136a6dSChris Costello.Pp 4984d6cd8eSMark MurrayWhen prompting for the current password, the authentication 508b136a6dSChris Costellomodule will use the prompt 5188de1238SRuslan Ermilov.Dq Li "Password for <principal>:" . 528b136a6dSChris Costello.Pp 5384d6cd8eSMark MurrayThe 548b136a6dSChris Costello.Fn pam_sm_setcred 5584d6cd8eSMark Murrayfunction stores the newly acquired credentials in a credentials cache, 5684d6cd8eSMark Murrayand sets the environment variable 578b136a6dSChris Costello.Ev KRB5CCNAME 5884d6cd8eSMark Murrayappropriately. 5984d6cd8eSMark MurrayThe credentials cache should be destroyed by the user at logout with 608b136a6dSChris Costello.Xr kdestroy 1 . 618b136a6dSChris Costello.Pp 6284d6cd8eSMark MurrayThe following options may be passed to the authentication module: 63e8b02a42SRuslan Ermilov.Bl -tag -width ".Cm use_first_pass" 6488de1238SRuslan Ermilov.It Cm debug 658b136a6dSChris Costello.Xr syslog 3 6684d6cd8eSMark Murraydebugging information at 678b136a6dSChris Costello.Dv LOG_DEBUG 6884d6cd8eSMark Murraylevel. 69ca0bdcddSMark Murray.It Cm no_warn 70ca0bdcddSMark Murraysuppress warning messages to the user. 71ca0bdcddSMark MurrayThese messages include 72ca0bdcddSMark Murrayreasons why the user's 73ca0bdcddSMark Murrayauthentication attempt was declined. 7488de1238SRuslan Ermilov.It Cm use_first_pass 7584d6cd8eSMark MurrayIf the authentication module is not the first in the stack, 7684d6cd8eSMark Murrayand a previous module obtained the user's password, that password is 7788de1238SRuslan Ermilovused to authenticate the user. 7888de1238SRuslan ErmilovIf this fails, the authentication 7984d6cd8eSMark Murraymodule returns failure without prompting the user for a password. 8084d6cd8eSMark MurrayThis option has no effect if the authentication module is 8184d6cd8eSMark Murraythe first in the stack, or if no previous modules obtained the 8284d6cd8eSMark Murrayuser's password. 8388de1238SRuslan Ermilov.It Cm try_first_pass 8484d6cd8eSMark MurrayThis option is similar to the 8588de1238SRuslan Ermilov.Cm use_first_pass 8684d6cd8eSMark Murrayoption, except that if the previously obtained password fails, the 8784d6cd8eSMark Murrayuser is prompted for another password. 8888de1238SRuslan Ermilov.It Cm forwardable 8984d6cd8eSMark MurrayObtain forwardable Kerberos credentials for the user. 9088de1238SRuslan Ermilov.It Cm no_ccache 9188de1238SRuslan ErmilovDo not save the obtained credentials in a credentials cache. 9288de1238SRuslan ErmilovThis is a 9384d6cd8eSMark Murrayuseful option if the authentication module is used for services such 9488de1238SRuslan Ermilovas ftp or pop, where the user would not be able to destroy them. 9588de1238SRuslan Ermilov[This 9684d6cd8eSMark Murrayis not a recommendation to use the module for those services.] 9788de1238SRuslan Ermilov.It Cm ccache Ns = Ns Ar name 9888de1238SRuslan ErmilovUse 9988de1238SRuslan Ermilov.Ar name 10088de1238SRuslan Ermilovas the credentials cache. 10188de1238SRuslan Ermilov.Ar name 10288de1238SRuslan Ermilovmust be in the form 10388de1238SRuslan Ermilov.Ar type : Ns Ar residual . 10484d6cd8eSMark MurrayThe special tokens 10588de1238SRuslan Ermilov.Ql %u , 10688de1238SRuslan Ermilovto designate the decimal UID of the user; 10784d6cd8eSMark Murrayand 10888de1238SRuslan Ermilov.Ql %p , 10988de1238SRuslan Ermilovto designate the current process ID; can be used in 11088de1238SRuslan Ermilov.Ar name . 111*551e75c7SMartin Matuska.It Cm no_user_check 112*551e75c7SMartin MatuskaDo not verify if a user exists on the local system. This option implies the 113*551e75c7SMartin Matuska.Cm no_ccache 114*551e75c7SMartin Matuskaoption because there is no secure local uid/gid for the cache file. 1158b136a6dSChris Costello.El 1168b136a6dSChris Costello.Ss Kerberos 5 Account Management Module 11784d6cd8eSMark MurrayThe Kerberos 5 account management component 11884d6cd8eSMark Murrayprovides a function to perform account management, 1198b136a6dSChris Costello.Fn pam_sm_acct_mgmt . 12084d6cd8eSMark MurrayThe function verifies that the authenticated principal is allowed 12184d6cd8eSMark Murrayto login to the local user account by calling 1228b136a6dSChris Costello.Fn krb5_kuserok 12388de1238SRuslan Ermilov(which checks the user's 12488de1238SRuslan Ermilov.Pa .k5login 12588de1238SRuslan Ermilovfile). 1268b136a6dSChris Costello.Ss Kerberos 5 Password Management Module 12784d6cd8eSMark MurrayThe Kerberos 5 password management component 12884d6cd8eSMark Murrayprovides a function to change passwords 1298b136a6dSChris Costello.Pq Fn pam_sm_chauthtok . 1308b136a6dSChris CostelloThe username supplied (the 13184d6cd8eSMark Murrayuser running the 1328b136a6dSChris Costello.Xr passwd 1 13384d6cd8eSMark Murraycommand, or the username given as an argument) is mapped into 13484d6cd8eSMark Murraya Kerberos principal name, using the same technique as in 13588de1238SRuslan Ermilovthe authentication module. 13688de1238SRuslan ErmilovNote that if a realm name was 13784d6cd8eSMark Murrayexplicitly supplied during authentication, but not during 13884d6cd8eSMark Murraya password change, the mapping 13984d6cd8eSMark Murraydone by the password management module may not result in the 14084d6cd8eSMark Murraysame principal as was used for authentication. 1418b136a6dSChris Costello.Pp 14284d6cd8eSMark MurrayUnlike when 14388de1238SRuslan Ermilovchanging a 14488de1238SRuslan Ermilov.Ux 14588de1238SRuslan Ermilovpassword, the password management module will 14684d6cd8eSMark Murrayallow any user to change any principal's password (if the user knows 14788de1238SRuslan Ermilovthe principal's old password, of course). 14888de1238SRuslan ErmilovAlso unlike 14988de1238SRuslan Ermilov.Ux , 15088de1238SRuslan Ermilovroot 15184d6cd8eSMark Murrayis always prompted for the principal's old password. 1528b136a6dSChris Costello.Pp 15384d6cd8eSMark MurrayThe password management module uses the same heuristics as 1548b136a6dSChris Costello.Xr kpasswd 1 15584d6cd8eSMark Murrayto determine how to contact the Kerberos password server. 1568b136a6dSChris Costello.Pp 15784d6cd8eSMark MurrayThe following options may be passed to the password management 15884d6cd8eSMark Murraymodule: 159e8b02a42SRuslan Ermilov.Bl -tag -width ".Cm use_first_pass" 16088de1238SRuslan Ermilov.It Cm debug 16188de1238SRuslan Ermilov.Xr syslog 3 16284d6cd8eSMark Murraydebugging information at 1638b136a6dSChris Costello.Dv LOG_DEBUG 16484d6cd8eSMark Murraylevel. 16588de1238SRuslan Ermilov.It Cm use_first_pass 16684d6cd8eSMark MurrayIf the password management module is not the first in the stack, 16784d6cd8eSMark Murrayand a previous module obtained the user's old password, that password is 16888de1238SRuslan Ermilovused to authenticate the user. 16988de1238SRuslan ErmilovIf this fails, the password 17084d6cd8eSMark Murraymanagement 17184d6cd8eSMark Murraymodule returns failure without prompting the user for the old password. 17284d6cd8eSMark MurrayIf successful, the new password entered to the previous module is also 17388de1238SRuslan Ermilovused as the new Kerberos password. 17488de1238SRuslan ErmilovIf the new password fails, 17584d6cd8eSMark Murraythe password management module returns failure without 17684d6cd8eSMark Murrayprompting the user for a new password. 17788de1238SRuslan Ermilov.It Cm try_first_pass 17884d6cd8eSMark MurrayThis option is similar to the 17988de1238SRuslan Ermilov.Cm use_first_pass 18084d6cd8eSMark Murrayoption, except that if the previously obtained old or new passwords fail, 18184d6cd8eSMark Murraythe user is prompted for them. 1828b136a6dSChris Costello.El 1838b136a6dSChris Costello.Ss Kerberos 5 Session Management Module 18484d6cd8eSMark MurrayThe Kerberos 5 session management component 18584d6cd8eSMark Murrayprovides functions to initiate 1868b136a6dSChris Costello.Pq Fn pam_sm_open_session 18784d6cd8eSMark Murrayand terminate 1888b136a6dSChris Costello.Pq Fn pam_sm_close_session 18988de1238SRuslan Ermilovsessions. 19088de1238SRuslan ErmilovSince session management is not defined under Kerberos 5, 19188de1238SRuslan Ermilovboth of these functions simply return success. 19288de1238SRuslan ErmilovThey are provided 19384d6cd8eSMark Murrayonly because of the naming conventions for PAM modules. 1948b136a6dSChris Costello.Sh ENVIRONMENT 1958b136a6dSChris Costello.Bl -tag -width "KRB5CCNAME" 1968b136a6dSChris Costello.It Ev KRB5CCNAME 19784d6cd8eSMark MurrayLocation of the credentials cache. 1988b136a6dSChris Costello.El 1998b136a6dSChris Costello.Sh FILES 200e8b02a42SRuslan Ermilov.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 20188de1238SRuslan Ermilov.It Pa /tmp/krb5cc_ Ns Ar uid 20288de1238SRuslan Ermilovdefault credentials cache 20388de1238SRuslan Ermilov.Ar ( uid 20488de1238SRuslan Ermilovis the decimal UID of the user). 2058b136a6dSChris Costello.It Pa $HOME/.k5login 20684d6cd8eSMark Murrayfile containing Kerberos principals that are allowed access. 2078b136a6dSChris Costello.El 2088b136a6dSChris Costello.Sh SEE ALSO 2098b136a6dSChris Costello.Xr kdestroy 1 , 2108b136a6dSChris Costello.Xr passwd 1 , 2118b136a6dSChris Costello.Xr syslog 3 , 2128b136a6dSChris Costello.Xr pam.conf 5 , 21388de1238SRuslan Ermilov.Xr pam 8 2148b136a6dSChris Costello.Sh NOTES 21584d6cd8eSMark MurrayApplications should not call 2168b136a6dSChris Costello.Fn pam_authenticate 21784d6cd8eSMark Murraymore than once between calls to 2188b136a6dSChris Costello.Fn pam_start 21984d6cd8eSMark Murrayand 2208b136a6dSChris Costello.Fn pam_end 22184d6cd8eSMark Murraywhen using the Kerberos 5 PAM module. 222