263 lines
8.9 KiB
Groff
263 lines
8.9 KiB
Groff
.\" $NetBSD: pam_krb5.8,v 1.11 2008/12/02 22:52:06 reed Exp $
|
|
.\" $FreeBSD: src/lib/libpam/modules/pam_krb5/pam_krb5.8,v 1.6 2001/11/24 23:41:32 dd Exp $
|
|
.\"
|
|
.\" Copyright (c) Frank Cusack, 1999-2001. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notices, and the entire permission notice in its entirety,
|
|
.\" including the disclaimer of warranties.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote
|
|
.\" products derived from this software without specific prior
|
|
.\" written permission.
|
|
.\"
|
|
.\" ALTERNATIVELY, this product may be distributed under the terms of
|
|
.\" the GNU Public License, in which case the provisions of the GPL are
|
|
.\" required INSTEAD OF the above restrictions. (This clause is
|
|
.\" necessary due to a potential bad interaction between the GPL and
|
|
.\" the restrictions contained in a BSD-style copyright.)
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
|
|
.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
|
|
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd March 10, 2007
|
|
.Dt PAM_KRB5 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pam_krb5
|
|
.Nd Kerberos 5 PAM module
|
|
.Sh SYNOPSIS
|
|
.Op Ar service-name
|
|
.Ar module-type
|
|
.Ar control-flag
|
|
.Pa pam_krb5
|
|
.Op Ar arguments
|
|
.Sh DESCRIPTION
|
|
The Kerberos 5 service module for PAM
|
|
provides functionality for three PAM categories:
|
|
authentication,
|
|
account management,
|
|
and password management.
|
|
It also provides null functions for session management.
|
|
.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 \*[Lt]principal\*[Gt]:" .
|
|
.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 renewable Ns = Ns Ar timeperiod
|
|
Obtain renewable Kerberos credentials for the user.
|
|
The renewable time can be specified, or it defaults to one month.
|
|
Since spaces are not allowed in the pam configuration time, underscores
|
|
are used to form parseable times (e.g., 1_month).
|
|
.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.
|
|
.Sh SECURITY CONSIDERATIONS
|
|
The
|
|
.Nm
|
|
module implements what is fundamentally a password authentication scheme.
|
|
It does not use a Kerberos 5 exchange between client and server, but rather
|
|
authenticates the password provided by the client against the Kerberos KDC.
|
|
Therefore, care should be taken to only use this module over a secure session
|
|
.Po
|
|
secure TTY, encrypted session, etc.
|
|
.Pc ,
|
|
otherwise the user's Kerberos 5 password could be compromised.
|