xref: /freebsd/lib/libpam/modules/pam_krb5/pam_krb5.8 (revision 551e75c7af421b58b9ba54d639af1e5f7a79ca23)
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