On Wed, Nov 11, 2009 at 04:06:00PM -0800, Gary Winiger wrote:
>
> > I think this is
> > sufficient for now and it doesn't preclude adding module options or a
> > krb5.conf stanza (or even user_attr(4) name=value pairs) to control this
> > in the future.
>
> Hopefully pam_eval will be a longer term way of doing this.
>
> > I'm happy with the latest spec that has been proposed.
>
> I asked for through today at the meeting. Here's my summary:
[points answered in other e-mail deleted]
> 7 Has the project team coordianted with SunRay (SRSS) team
> (as the primary implementor of smartcards)? Has the project
> team coordinated with the TX team and how this may work/affect
> the multi-level desktop?
I am interacting with the SunRay team now and will check with the TX
team.
> Bottom line, IMO, 3, 4 and 5 need to be addressed in the spec. If they
> have been, please point me to where? I'll "hold my nose[tm]" relative
> to 1 and 2.
>
> Thanks for the extra time,
Sure. Below is the updated pam_krb5(5) man page diffs:
Standards, Environments, and Macros pam_krb5(5)
NAME
pam_krb5 - authentication, account, session, and password
management PAM modules for Kerberos V5
SYNOPSIS
/usr/lib/security/pam_krb5.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, pam_sm_authenticate(), and
to manage the Kerberos credentials cache, pam_sm_setcred().
pam_sm_authenticate() 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 at 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 "verify_ap_req_nofail = 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.
+ Note that if pam_sm_authenticate() is called and the
+ PAM_AUTHTOK password item has not been set, which is
+ typically the case when pam_krb5 is stacked before
+ pam_authtok_get, the Kerberos V5 authentication module will
+ try to do PKINIT preauthentication if both the system and
+ the KDC are configured to support this type of
+ preauthentication. This form of preauthentication uses a
+ user's certificate and private key to acquire the user's
+ initial Kerberos credential (TGT). Use of smartcards is
+ supported by PKINIT preauthentication. See krb5.conf(4) for
+ more details on PKINIT configuration. Also note that this
+ form of preauthentication is typically useful for services
+ where the system on which the auth stack is being processed
+ has access to the user's certificate and private key.
+ pam_krb5 does not set any PAM items when doing PKINIT
+ authentication.
+
+ If the PAM_AUTHTOK password item has been set when
+ pam_sm_authenticate() is called, which is the case when
+ pam_krb5 is stacked after pam_authtok_get, the Kerberos V5
+ authentication module will only try password based
+ preauthentication.
+ If it is desirable to initially have the Kerberos V5
+ authentication module try PKINIT preauthentication and fall
+ back to password based preauthentication then the sufficient
+ or optional control flags must be provided for the instance
+ of pam_krb5 stacked above pam_authtok_get and another
+ instance of pam_krb5 must be stacked below pam_authtok_get.
+ If there are PAM modules other than pam_krb5 that must be
+ evaluated below pam_authtok_get then the control flag should
+ be set to optional for the instance of pam_krb5 above
+ pam_authtok_get otherwise the control flag should be set to
+ sufficient.
+
+ Note that only two instances of pam_krb5 are supported in a
+ auth stack.
+
pam_sm_authenticate(3PAM) may be passed the following flag:
PAM_DISALLOW_NULL_AUTHTOK
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 pam_krb5(5)
pam_sm_setcred() 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.
PAM_ESTABLISH_CRED
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, PAM_CRED_UNAVAIL is returned.
PAM_DELETE_CRED
This flag has no effect on the credential cache and
always returns PAM_SUCCESS. 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.
PAM_REINITIALIZE_CRED
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.
PAM_REFRESH_CRED
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 pam_krb5(5)
debug Provides syslog(3C) debugging information at
LOG_DEBUG level.
nowarn Turns off warning messages.
Kerberos V5 Account Management Module
The Kerberos account management component provides a func-
tion to perform account management, pam_sm_acct_mgmt(). This
function checks to see if the pam_krb5 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
LOG_DEBUG 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 pam_sm_open_session() and terminate
pam_sm_close_session() Kerberos sessions. For Kerberos V5,
both pam_sm_open_session and pam_sm_close_session() are null
functions, returning PAM_IGNORE.
Kerberos V5 Password Management Module
The Kerberos V5 password management component provides a
function to change passwords, pam_sm_chauthtok(), in the Key
Distribution Center (KDC) database. The following flags may
be passed to pam_sm_chauthtok(3PAM):
PAM_CHANGE_EXPIRED_AUTHTOK
The password service should only update the user's Ker-
beros password if it is expired. Otherwise, this func-
tion returns PAM_IGNORE. The default behaviour is to
always change the user's Kerberos password.
PAM_PRELIM_CHECK
This is a null function that always returns PAM_IGNORE.
PAM_UPDATE_AUTHTOK
SunOS 5.11 Last change: 8 Apr 2008 3
Standards, Environments, and Macros pam_krb5(5)
This flag is necessary to change the user's Kerberos
password. If this flag is not set, pam_krb5 returns
PAM_SYSTEM_ERR.
The following option can be passed to the Kerberos V5 pass-
word module:
debug Provides syslog(3C) debugging information at
LOG_DEBUG level.
ERRORS
The following error codes are returned for
pam_sm_authenticate():
PAM_AUTH_ERR Authentication failure
PAM_BUF_ERR Memory buffer error.
PAM_IGNORE The user is "root" and the root key
exists in the default keytab.
PAM_SUCCESS Successfully obtained Kerberos creden-
tials .
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was
requested.
The following error codes are returned for pam_sm_setcred():
PAM_AUTH_ERR Authentication failure.
PAM_BUF_ERR Memory buffer error.
PAM_IGNORE 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 pam_krb5(5)
PAM_SYSTEM_ERR System error.
PAM_SUCCESS Successfully modified the Kerberos creden-
tial cache.
The following error codes are returned for
pam_sm_acct_mgmt():
PAM_AUTH_ERR Authentication failure.
PAM_IGNORE Kerberos service module
pam_sm_authenticate() was never
called, or the user is "root" and
the root key exists in the default
keytab.
PAM_NEW_AUTHTOK_REQD Obtain new authentication token from
the user.
PAM_SERVICE_ERR Error in underlying service module.
PAM_SUCCESS Kerberos principal account is valid.
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was
requested.
The following error code is returned for
pam_sm_open_session() and pam_sm_close_session():
PAM_IGNORE These two functions are null functions in
pam_krb5:
The following error codes are returned for
pam_sm_chauthtok():
PAM_AUTH_ERR Authentication failure.
SunOS 5.11 Last change: 8 Apr 2008 5
Standards, Environments, and Macros pam_krb5(5)
PAM_IGNORE The user has not been authenticated
by Kerberos service module
pam_sm_authenticate(), or the user
is "root" and the root key exists in
the default keytab.
PAM_NEW_AUTHTOK_REQD User's Kerberos password has
expired.
PAM_SERVICE_ERR Error in module. At least one input
parameter is missing.
PAM_SYSTEM_ERR System error.
PAM_USER_UNKNOWN An unknown Kerberos principal was
requested.
PAM_SUCCESS Successfully changed the user's Ker-
beros password.
EXAMPLES
Example 1 Authenticate Users Through Kerberos as First
- Choice
+ Choice using password based preauthentication
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 pam_smartcard.so.1
dtlogin auth requisite pam_authtok_get.so.1
dtlogin auth required pam_dhkeys.so.1
dtlogin auth required pam_unix_cred.so.1
dtlogin auth sufficient pam_krb5.so.1
dtlogin auth required pam_unix_auth.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 pam_krb5(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 pam_roles.so.1
other account required pam_unix_account.so.1
other account required pam_krb5.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 pam_dhkeys.so.1
other password requisite pam_authtok_get.so.1
other password requisite pam_authtok_check.so.1
other password sufficient pam_krb5.so.1
other password required pam_authtok_store.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
+ Example 2 Authenticate Users Through Kerberos Only using
+ password based preauthentication
The following example allows authentication only to users
that have Kerberos-based accounts.
dtlogin auth requisite pam_smartcard.so.1
dtlogin auth requisite pam_authtok_get.so.1
dtlogin auth required pam_dhkeys.so.1
dtlogin auth required pam_unix_cred.so.1
dtlogin auth binding pam_krb5.so.1
dtlogin auth required pam_unix_auth.so.1
SunOS 5.11 Last change: 8 Apr 2008 7
Standards, Environments, and Macros pam_krb5(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 pam_roles.so.1
other account required pam_unix_account.so.1
other account required pam_krb5.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 pam_dhkeys.so.1
other password requisite pam_authtok_get.so.1
other password requisite pam_authtok_check.so.1
other password binding pam_krb5.so.1
other password required pam_authtok_store.so.1
- Example 3 Authenticate Through Kerberos Optionally
+ Example 3 Authenticate Through Kerberos Optionally using
+ password based preauthentication
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 pam_smartcard.so.1
dtlogin auth requisite pam_authtok_get.so.1
dtlogin auth required pam_dhkeys.so.1
SunOS 5.11 Last change: 8 Apr 2008 8
Standards, Environments, and Macros pam_krb5(5)
dtlogin auth required pam_unix_cred.so.1
dtlogin auth required pam_unix_auth.so.1
dtlogin auth optional pam_krb5.so.1
The rest of the configuration is as follows:
other account requisite pam_roles.so.1
other account required pam_unix_account.so.1
other account required pam_krb5.so.1
other password required pam_dhkeys.so.1
other password requisite pam_authtok_get.so.1
other password requisite pam_authtok_check.so.1
other password required pam_authtok_store.so.1
other password optional pam_krb5.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.
+ Example 4: Authenticate Users Through Kerberos PKINIT as First Choice
+
+ The following is an excerpt of a sample pam.conf configuration file
+ that authenticates users through the Kerberos authentication
+ service and authenticates through the Unix login only if the
+ Kerberos authentication (using PKINIT) 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
+ login. Note, the user is prompted once for the PIN by pam_krb5.
+
+ login auth required pam_unix_cred.so.1
+ login auth sufficient pam_krb5.so.1
+ login auth requisite pam_authtok_get.so.1
+ login auth required pam_dhkeys.so.1
+ login auth required pam_unix_auth.so.1
+
+ Example 5: Authenticate Users Through Kerberos PKINIT Only
+
+ The following example allows authentication only to users that have
+ Kerberos-based accounts requiring PKINIT preauth.
+
+ login auth required pam_unix_cred.so.1
+ login auth required pam_krb5.so.1
+
+ Example 6: Authenticate Users Through Kerberos PKINIT Optionally
+
+ The following example allows users to acquire a Kerberos credential
+ using PKINIT preauth if they have a Kerberos account. Whether
+ pam_krb5 succeeds or fails the user must provide their Unix password
+ in order to login.
+
+ login auth required pam_unix_cred.so.1
+ login auth optional pam_krb5.so.1
+ login auth requisite pam_authtok_get.so.1
+ login auth required pam_unix_auth.so.1
+
+ Example 7: Authenticate Users Through Kerberos PKINIT as a
+ requirement.
+
+ The following example allows users to login if pam_krb5 is able to
+ acquire a Kerberos credential via PKINT preauth and in addition must
+ provide their Unix password to pam_unix_auth.
+
+ login auth required pam_unix_cred.so.1
+ login auth required pam_krb5.so.1
+ login auth requisite pam_authtok_get.so.1
+ login auth required pam_unix_auth.so.1
+
+ Example 8: Authenticate Users Through Kerberos PKINIT, fall
+ back to password based krb auth if PKINIT fails.
+
+ The following example allows users to acquire a Kerberos credential
+ using PKINIT preauth or using password based preauth if PKINIT
+ fails. If PKINIT succeeds the user will not be prompted for their
+ password. Note, if pam_krb5 PKINIT succeeds, the second instance of
+ pam_krb5 will not try password preauth and will return success.
+ If PKINIT fails the user will be prompted for their Kerberos
+ password.
+
+ login auth required pam_unix_cred.so.1
+ login auth sufficient pam_krb5.so.1
+ login auth requisite pam_authtok_get.so.1
+ login auth required pam_krb5.so.1
+
+ Example 9: Require users to authenticate either through
+ Kerberos PKINIT or fall back to password based krb auth if
+ PKINIT fails and authenticate with other required PAM
+ modules.
+
+ The following example allows users to acquire a Kerberos credential
+ using PKINIT preauth or using password based preauth if PKINIT
+ fails. Note, if pam_krb5 PKINIT succeeds, the second instance of pam_krb5
+ will not try password preauth and will just return success. If
+ pam_krb5 PKINIT fails the second instance of pam_krb5 will try
+ password based preauth and return success or failure.
+
+ login auth required pam_unix_cred.so.1
+ login auth optional pam_krb5.so.1
+ login auth requisite pam_authtok_get.so.1
+ login auth required pam_krb5.so.1
+ login auth required pam_dhkeys.so.1
+ login auth required pam_unix_auth.so.1
+
+ Example 10: Require users to authenticate either through
+ Kerberos PKINIT or fall back to pam_pkcs11 auth if
+ PKINIT fails.
+
+ The following example allows users to acquire a Kerberos credential
+ using PKINIT preauth or if that fails use pam_pkcs11 to
+ validate the user's PIN using their certificate and private
+ key.
+
+ login auth required pam_unix_cred.so.1
+ login auth sufficient pam_krb5.so.1
+ login auth sufficient pam_pkcs11.so.1
+
+
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
SEE ALSO
kdestroy(1), kinit(1), kpasswd(1), passwd(1),
ktkt_warnd(1M), libpam(3LIB), pam(3PAM), pam_sm(3PAM),
pam_sm_acct_mgmt(3PAM), pam_sm_authenticate(3PAM),
pam_sm_chauthtok(3PAM), pam_sm_close_session(3PAM),
pam_sm_open_session(3PAM), pam_sm_setcred(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 pam_krb5(5)
On successful acquisition of initial credentials (ticket-
granting ticket), ktkt_warnd(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
--
Will Fiveash
Sun Microsystems Inc.
http://opensolaris.org/os/project/kerberos/
Sent from mutt, a sweet ASCII MUA
