Standards, Environments, and Macros pamkrb5(5)
NAME
pamkrb5 - authentication, account, session, and password
management PAM modules for Kerberos V5
SYNOPSIS
/usr/lib/security/pamkrb5.so.1
DESCRIPTION
The Kerberos V5 service module for PAM provides functional-
ity for all four PAM modules: authentication, account
management, session management, and password management. The
service 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.
Kerberos Authentication Module
The Kerberos V5 authentication component provides functions
to verify the identity of a user, pamsmauthenticate(), and
to manage the Kerberos credentials cache, pamsmsetcred().
pamsmauthenticate() authenticates a user principal through
the Kerberos authentication service. If the authentication
request is successful, the authentication service sends a
ticket-granting ticket (TGT) back to the service module,
which then verifies that the TGT came from a valid Key Dis-
tribution Center (KDC) by attempting to get a service ticket
for the local host service. For this to succeed, the local
host's keytab file (/etc/krb5/krb5.keytab) must contain the
entry for the local host service. For example, in the file
host/hostname.com@REALM, hostname.com is the fully qualified
local hostname and REALM is the default realm of the local
host as defined in /etc/krb5/krb5.conf. If the host entry is
not found in the keytab file, the authentication fails.
Administrators may optionally disable this "strict" verifi-
cation by setting "verifyapreqnofail = false" in
/etc/krb5/krb5.conf. See krb5.conf(4) for more details on
this option. This allows TGT verification to succeed in the
absence of a keytab host principal entry.
pamsmauthenticate(3PAM) may be passed the following flag:
PAMDISALOWNULAUTHTOK
This flag is ignored. The Kerberos authentication
mechanism will not allow an empty password string by
default.
SunOS 5.11 Last change: 8 Apr 2008 1
Standards, Environments, and Macros pamkrb5(5)
pamsmsetcred() creates and modifies the user's credential
cache. This function initializes the user's credential
cache, if it does not already exist, and stores the initial
credentials for later use by Kerberized network applica-
tions. The following flags may be set in the flags field.
They are best described by their effect on the user's
credential cache.
PAMESTABLISHCRED
Stores the initial credentials in the user's credential
cache so that the user may access Kerberos network ser-
vices. If a successful authentication pass was made, the
new credentials are stored in the credential cache,
overwriting any existing credentials that were previ-
ously stored. If an unsuccessful authentication pass was
made, PAMCREDUNAVAIL is returned.
PAMDELETECRED
This flag has no effect on the credential cache and
always returns PAMSUCES. The credential cache is not
deleted because there is no accurate method to determine
if the credentials are needed by another process. The
credential cache may be deleted with the kdestroy(1)
command.
PAMREINITIALIZECRED
Deletes the user's existing credential cache, if it
exists, and creates a new credential cache. The new
credentials are stored in the new cache and the user's
ticket lifetime and renewable life time values are
reset.
PAMREFRESHCRED
Does not require a previous authentication pass, but if
a successful one is made, the new credentials are stored
in the credential cache. If a previous authentication
pass was not made or was unsuccessful, an attempt to
renew the existing credentials is made. Note that this
function fails if the user's renewable ticket lifetime
is expired.
The following options can be passed to the Kerberos V5
authentication module:
SunOS 5.11 Last change: 8 Apr 2008 2
Standards, Environments, and Macros pamkrb5(5)
debug Provides syslog(3C) debugging information at
LOGDEBUG level.
nowarn Turns off warning messages.
Kerberos V5 Account Management Module
The Kerberos account management component provides a func-
tion to perform account management, pamsmacctmgmt(). This
function checks to see if the pamkrb5 authentication module
has noted that the user's password has not expired. The fol-
lowing options may be passed in to the Kerberos V5 account
management module:
debug Provides syslog(3C) debugging information at
LOGDEBUG level
nowarn Turns off warning messages. Also, does not query
KDC for impending password expiration information
used to warn the user.
Kerberos V5 Session Management Module
The Kerberos V5 session management component provides func-
tions to initiate pamsmopensession() and terminate
pamsmclosesession() Kerberos sessions. For Kerberos V5,
both pamsmopensession and pamsmclosesession() are null
functions, returning PAMIGNORE.
Kerberos V5 Password Management Module
The Kerberos V5 password management component provides a
function to change passwords, pamsmchauthtok(), in the Key
Distribution Center (KDC) database. The following flags may
be passed to pamsmchauthtok(3PAM):
PAMCHANGEXPIREDAUTHTOK
The password service should only update the user's Ker-
beros password if it is expired. Otherwise, this func-
tion returns PAMIGNORE. The default behaviour is to
always change the user's Kerberos password.
PAMPRELIMCHECK
This is a null function that always returns PAMIGNORE.
PAMUPDATEAUTHTOK
SunOS 5.11 Last change: 8 Apr 2008 3
Standards, Environments, and Macros pamkrb5(5)
This flag is necessary to change the user's Kerberos
password. If this flag is not set, pamkrb5 returns
PAMSYSTEMER.
The following option can be passed to the Kerberos V5 pass-
word module:
debug Provides syslog(3C) debugging information at
LOGDEBUG level.
ERORS
The following error codes are returned for
pamsmauthenticate():
PAMAUTHER Authentication failure
PAMBUFER Memory buffer error.
PAMIGNORE The user is "root" and the root key
exists in the default keytab.
PAMSUCES Successfully obtained Kerberos creden-
tials .
PAMSYSTEMER System error.
PAMUSERUNKNOWN An unknown Kerberos principal was
requested.
The following error codes are returned for pamsmsetcred():
PAMAUTHER Authentication failure.
PAMBUFER Memory buffer error.
PAMIGNORE The user is "root" and the root key exists
in the default keytab.
SunOS 5.11 Last change: 8 Apr 2008 4
Standards, Environments, and Macros pamkrb5(5)
PAMSYSTEMER System error.
PAMSUCES Successfully modified the Kerberos creden-
tial cache.
The following error codes are returned for
pamsmacctmgmt():
PAMAUTHER Authentication failure.
PAMIGNORE Kerberos service module
pamsmauthenticate() was never
called, or the user is "root" and
the root key exists in the default
keytab.
PAMNEWAUTHTOKREQD Obtain new authentication token from
the user.
PAMSERVICER Error in underlying service module.
PAMSUCES Kerberos principal account is valid.
PAMSYSTEMER System error.
PAMUSERUNKNOWN An unknown Kerberos principal was
requested.
The following error code is returned for
pamsmopensession() and pamsmclosesession():
PAMIGNORE These two functions are null functions in
pamkrb5:
The following error codes are returned for
pamsmchauthtok():
PAMAUTHER Authentication failure.
SunOS 5.11 Last change: 8 Apr 2008 5
Standards, Environments, and Macros pamkrb5(5)
PAMIGNORE The user has not been authenticated
by Kerberos service module
pamsmauthenticate(), or the user
is "root" and the root key exists in
the default keytab.
PAMNEWAUTHTOKREQD User's Kerberos password has
expired.
PAMSERVICER Error in module. At least one input
parameter is missing.
PAMSYSTEMER System error.
PAMUSERUNKNOWN An unknown Kerberos principal was
requested.
PAMSUCES Successfully changed the user's Ker-
beros password.
EXAMPLES
Example 1 Authenticate Users Through Kerberos as First
Choice
The following is an excerpt of a sample pam.conf configura-
tion file that authenticates users through the Kerberos
authentication service and authenticates through the Unix
login only if the Kerberos authentication fails. This
arrangement is helpful when a majority of the users are
networked by means of Kerberos and when there are only a few
non-Kerberos type user accounts, such as root. The service
illustrated below is for dtlogin.
dtlogin auth requisite pamsmartcard.so.1
dtlogin auth requisite pamauthtokget.so.1
dtlogin auth required pamdhkeys.so.1
dtlogin auth required pamunixcred.so.1
dtlogin auth sufficient pamkrb5.so.1
dtlogin auth required pamunixauth.so.1
Note that these changes should not be made to the existing
krlogin, krsh, and ktelnet service entries. Those services
SunOS 5.11 Last change: 8 Apr 2008 6
Standards, Environments, and Macros pamkrb5(5)
require Kerberos authentication, so using a seemingly suffi-
cient control flag would not provide the necessary func-
tionality for privacy and integrity. There should be no need
to change those entries.
The following entries check for password expiration when
dealing with Kerberos and Unix password aging policies:
other account requisite pamroles.so.1
other account required pamunixaccount.so.1
other account required pamkrb5.so.1
The following entries would change the Kerberos password of
the user and continue to change the Unix login password only
if the Kerberos password change had failed:
other password required pamdhkeys.so.1
other password requisite pamauthtokget.so.1
other password requisite pamauthtokcheck.so.1
other password sufficient pamkrb5.so.1
other password required pamauthtokstore.so.1
When changing Kerberos based user's password, use
kpasswd(1). When changing a non-Kerberos user's password, it
is recommended that the repository is specified (-r) with
the passwd(1) command.
Example 2 Authenticate Users Through Kerberos Only
The following example allows authentication only to users
that have Kerberos-based accounts.
dtlogin auth requisite pamsmartcard.so.1
dtlogin auth requisite pamauthtokget.so.1
dtlogin auth required pamdhkeys.so.1
dtlogin auth required pamunixcred.so.1
dtlogin auth binding pamkrb5.so.1
dtlogin auth required pamunixauth.so.1
SunOS 5.11 Last change: 8 Apr 2008 7
Standards, Environments, and Macros pamkrb5(5)
Typically, you would have another service specified in the
pam.conf file that would allow local users, such as data-
base, web server, system administrator accounts, to log in
to the host machine. For example, the service name "login"
could be used for these users. Note that these users should
not belong to any roles.
The rest of the module types look similar to that shown in
the previous example:
other account requisite pamroles.so.1
other account required pamunixaccount.so.1
other account required pamkrb5.so.1
With binding specified in the following, it is important
that non-Kerberos users specify the repository in which they
reside using the -r option with the passwd(1) command. This
configuration is also based on the assumptions that:
o Kerberos users maintain only their Kerberos pass-
words;
o changing their Unix password is not necessary,
given that they are authenticated only through
their Kerberos passwords when logging in.
other password required pamdhkeys.so.1
other password requisite pamauthtokget.so.1
other password requisite pamauthtokcheck.so.1
other password binding pamkrb5.so.1
other password required pamauthtokstore.so.1
Example 3 Authenticate Through Kerberos Optionally
This configuration is helpful when the majority of users are
non-Kerberos users and would like to authenticate through
Kerberos if they happened to exist in the Kerberos database.
The effect of this is similar to users voluntarily executing
kinit(1) after they have successfully logged in:
dtlogin auth requisite pamsmartcard.so.1
dtlogin auth requisite pamauthtokget.so.1
dtlogin auth required pamdhkeys.so.1
SunOS 5.11 Last change: 8 Apr 2008 8
Standards, Environments, and Macros pamkrb5(5)
dtlogin auth required pamunixcred.so.1
dtlogin auth required pamunixauth.so.1
dtlogin auth optional pamkrb5.so.1
The rest of the configuration is as follows:
other account requisite pamroles.so.1
other account required pamunixaccount.so.1
other account required pamkrb5.so.1
other password required pamdhkeys.so.1
other password requisite pamauthtokget.so.1
other password requisite pamauthtokcheck.so.1
other password required pamauthtokstore.so.1
other password optional pamkrb5.so.1
Non-Kerberos users should specify their respective reposi-
tories by using the -r option when changing their password
with the passwd(1) command.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Evolving
SEE ALSO
kdestroy(1), kinit(1), kpasswd(1), passwd(1),
ktktwarnd(1M), libpam(3LIB), pam(3PAM), pamsm(3PAM),
pamsmacctmgmt(3PAM), pamsmauthenticate(3PAM),
pamsmchauthtok(3PAM), pamsmclosesession(3PAM),
pamsmopensession(3PAM), pamsmsetcred(3PAM), syslog(3C),
pam.conf(4), attributes(5), kerberos(5), krb5envvar(5)
NOTES
The interfaces in libpam(3LIB) are MT-Safe only if each
thread within the multi-threaded application uses its own
PAM handle.
SunOS 5.11 Last change: 8 Apr 2008 9
Standards, Environments, and Macros pamkrb5(5)
On successful acquisition of initial credentials (ticket-
granting ticket), ktktwarnd(1M) will be notified, to alert
the user when the initial credentials are about to expire.
SunOS 5.11 Last change: 8 Apr 2008 10
|
