218 lines
6.4 KiB
Groff
218 lines
6.4 KiB
Groff
.\"
|
|
.\" $Id: pam_krb5.5,v 1.5 2000/01/05 00:59:56 fcusack Exp $
|
|
.\" $FreeBSD$
|
|
.Dd January 15, 1999
|
|
.Dt PAM_KRB5 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pam_krb5
|
|
.Nd Kerberos 5 PAM module
|
|
.Sh SYNOPSIS
|
|
.Pa /usr/lib/pam_krb5.so
|
|
.Sh DESCRIPTION
|
|
The Kerberos 5 service module for PAM, typically
|
|
.Pa /usr/lib/pam_krb5.so ,
|
|
provides functionality for three PAM categories:
|
|
authentication,
|
|
account management,
|
|
and password management.
|
|
It also provides null functions for session management.
|
|
The
|
|
.Pa pam_krb5.so
|
|
module is a shared object
|
|
that can be dynamically loaded to provide
|
|
the necessary functionality upon demand.
|
|
Its path is specified in the
|
|
PAM configuration file.
|
|
.Ss Kerberos 5 Authentication Module
|
|
The Kerberos 5 authentication component
|
|
provides functions to verify the identity of a user
|
|
.Pq Fn pam_sm_authenticate
|
|
and to set user specific credentials
|
|
.Pq Fn pam_sm_setcred .
|
|
.Fn pam_sm_authenticate
|
|
converts the supplied username into a Kerberos principal,
|
|
by appending the default local realm name.
|
|
It also supports usernames with explicit realm names.
|
|
If a realm name is supplied, then upon a successful return, it
|
|
changes the username by mapping the principal name into a local username
|
|
(calling
|
|
.Fn krb5_aname_to_localname ) .
|
|
This typically just means
|
|
the realm name is stripped.
|
|
.Pp
|
|
It prompts the user for a password and obtains a new Kerberos TGT for
|
|
the principal.
|
|
The TGT is verified by obtaining a service
|
|
ticket for the local host.
|
|
.Pp
|
|
When prompting for the current password, the authentication
|
|
module will use the prompt
|
|
.Dq Li "Password for <principal>:" .
|
|
.Pp
|
|
The
|
|
.Fn pam_sm_setcred
|
|
function stores the newly acquired credentials in a credentials cache,
|
|
and sets the environment variable
|
|
.Ev KRB5CCNAME
|
|
appropriately.
|
|
The credentials cache should be destroyed by the user at logout with
|
|
.Xr kdestroy 1 .
|
|
.Pp
|
|
The following options may be passed to the authentication module:
|
|
.Bl -tag -width ".Cm use_first_pass"
|
|
.It Cm debug
|
|
.Xr syslog 3
|
|
debugging information at
|
|
.Dv LOG_DEBUG
|
|
level.
|
|
.It Cm no_warn
|
|
suppress warning messages to the user.
|
|
These messages include
|
|
reasons why the user's
|
|
authentication attempt was declined.
|
|
.It Cm use_first_pass
|
|
If the authentication module is not the first in the stack,
|
|
and a previous module obtained the user's password, that password is
|
|
used to authenticate the user.
|
|
If this fails, the authentication
|
|
module returns failure without prompting the user for a password.
|
|
This option has no effect if the authentication module is
|
|
the first in the stack, or if no previous modules obtained the
|
|
user's password.
|
|
.It Cm try_first_pass
|
|
This option is similar to the
|
|
.Cm use_first_pass
|
|
option, except that if the previously obtained password fails, the
|
|
user is prompted for another password.
|
|
.It Cm forwardable
|
|
Obtain forwardable Kerberos credentials for the user.
|
|
.It Cm no_ccache
|
|
Do not save the obtained credentials in a credentials cache.
|
|
This is a
|
|
useful option if the authentication module is used for services such
|
|
as ftp or pop, where the user would not be able to destroy them.
|
|
[This
|
|
is not a recommendation to use the module for those services.]
|
|
.It Cm ccache Ns = Ns Ar name
|
|
Use
|
|
.Ar name
|
|
as the credentials cache.
|
|
.Ar name
|
|
must be in the form
|
|
.Ar type : Ns Ar residual .
|
|
The special tokens
|
|
.Ql %u ,
|
|
to designate the decimal UID of the user;
|
|
and
|
|
.Ql %p ,
|
|
to designate the current process ID; can be used in
|
|
.Ar name .
|
|
.El
|
|
.Ss Kerberos 5 Account Management Module
|
|
The Kerberos 5 account management component
|
|
provides a function to perform account management,
|
|
.Fn pam_sm_acct_mgmt .
|
|
The function verifies that the authenticated principal is allowed
|
|
to login to the local user account by calling
|
|
.Fn krb5_kuserok
|
|
(which checks the user's
|
|
.Pa .k5login
|
|
file).
|
|
.Ss Kerberos 5 Password Management Module
|
|
The Kerberos 5 password management component
|
|
provides a function to change passwords
|
|
.Pq Fn pam_sm_chauthtok .
|
|
The username supplied (the
|
|
user running the
|
|
.Xr passwd 1
|
|
command, or the username given as an argument) is mapped into
|
|
a Kerberos principal name, using the same technique as in
|
|
the authentication module.
|
|
Note that if a realm name was
|
|
explicitly supplied during authentication, but not during
|
|
a password change, the mapping
|
|
done by the password management module may not result in the
|
|
same principal as was used for authentication.
|
|
.Pp
|
|
Unlike when
|
|
changing a
|
|
.Ux
|
|
password, the password management module will
|
|
allow any user to change any principal's password (if the user knows
|
|
the principal's old password, of course).
|
|
Also unlike
|
|
.Ux ,
|
|
root
|
|
is always prompted for the principal's old password.
|
|
.Pp
|
|
The password management module uses the same heuristics as
|
|
.Xr kpasswd 1
|
|
to determine how to contact the Kerberos password server.
|
|
.Pp
|
|
The following options may be passed to the password management
|
|
module:
|
|
.Bl -tag -width ".Cm use_first_pass"
|
|
.It Cm debug
|
|
.Xr syslog 3
|
|
debugging information at
|
|
.Dv LOG_DEBUG
|
|
level.
|
|
.It Cm use_first_pass
|
|
If the password management module is not the first in the stack,
|
|
and a previous module obtained the user's old password, that password is
|
|
used to authenticate the user.
|
|
If this fails, the password
|
|
management
|
|
module returns failure without prompting the user for the old password.
|
|
If successful, the new password entered to the previous module is also
|
|
used as the new Kerberos password.
|
|
If the new password fails,
|
|
the password management module returns failure without
|
|
prompting the user for a new password.
|
|
.It Cm try_first_pass
|
|
This option is similar to the
|
|
.Cm use_first_pass
|
|
option, except that if the previously obtained old or new passwords fail,
|
|
the user is prompted for them.
|
|
.El
|
|
.Ss Kerberos 5 Session Management Module
|
|
The Kerberos 5 session management component
|
|
provides functions to initiate
|
|
.Pq Fn pam_sm_open_session
|
|
and terminate
|
|
.Pq Fn pam_sm_close_session
|
|
sessions.
|
|
Since session management is not defined under Kerberos 5,
|
|
both of these functions simply return success.
|
|
They are provided
|
|
only because of the naming conventions for PAM modules.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width "KRB5CCNAME"
|
|
.It Ev KRB5CCNAME
|
|
Location of the credentials cache.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact
|
|
.It Pa /tmp/krb5cc_ Ns Ar uid
|
|
default credentials cache
|
|
.Ar ( uid
|
|
is the decimal UID of the user).
|
|
.It Pa $HOME/.k5login
|
|
file containing Kerberos principals that are allowed access.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr kdestroy 1 ,
|
|
.Xr passwd 1 ,
|
|
.Xr syslog 3 ,
|
|
.Xr pam.conf 5 ,
|
|
.Xr pam 8
|
|
.Sh NOTES
|
|
Applications should not call
|
|
.Fn pam_authenticate
|
|
more than once between calls to
|
|
.Fn pam_start
|
|
and
|
|
.Fn pam_end
|
|
when using the Kerberos 5 PAM module.
|