te
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
pam_krb5 - authentication, account, session, and password management PAM modules for Kerberos V5

pam_krb5.so.1

The Kerberos V5 service module for PAM, pam_krb5.so.1, provides functionality for all four PAM modules: authentication, account management, session management, and password management. The Kerberos V5 authentication component provides functions to verify the identity of a user, pam_sm_authenticate(3PAM), and to manage the Kerberos credentials cache, pam_sm_setcred(3PAM).

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 Distribution 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" verification by setting "verify_ap_req_nofail = false" in /etc/krb5/krb5.conf. See krb5.conf(5) for more details on this option. This allows TGT verification to succeed in the absence of a keytab host principal entry.

pam_sm_authenticate(3PAM) may be passed the following flag: PAM_DISALLOW_NULL_AUTHTOK

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 applications. 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

PAM_DELETE_CRED PAM_REINITIALIZE_CRED PAM_REFRESH_CRED

The following options can be passed to the Kerberos V5 authentication module: debug

nowarn The Kerberos account management component provides a function 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 following options may be passed in to the Kerberos V5 account management module: debug nowarn The Kerberos V5 session management component provides functions 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. 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 PAM_PRELIM_CHECK PAM_UPDATE_AUTHTOK

The following option can be passed to the Kerberos V5 password module: debug

The following error codes are returned for pam_sm_authenticate(): PAM_AUTH_ERR PAM_BUF_ERR PAM_IGNORE PAM_SUCCESS PAM_SYSTEM_ERR PAM_USER_UNKNOWN

The following error codes are returned for pam_sm_setcred(): PAM_AUTH_ERR

PAM_BUF_ERR PAM_IGNORE PAM_SYSTEM_ERR PAM_SUCCESS

The following error codes are returned for pam_sm_acct_mgmt(): PAM_AUTH_ERR

PAM_IGNORE PAM_NEW_AUTHTOK_REQD PAM_SERVICE_ERR PAM_SUCCESS PAM_SYSTEM_ERR PAM_USER_UNKNOWN

The following error code is returned for pam_sm_open_session() and pam_sm_close_session(): PAM_IGNORE

The following error codes are returned for pam_sm_chauthtok(): PAM_AUTH_ERR

PAM_IGNORE PAM_NEW_AUTHTOK_REQD PAM_SERVICE_ERR PAM_SYSTEM_ERR PAM_USER_UNKNOWN PAM_SUCCESS Example 1 Authenticate Users Through Kerberos 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 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 require Kerberos authentication, so using a seemingly sufficient control flag would not provide the necessary functionality 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

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

Typically, you would have another service specified in the pam.conf file that would allow local users, such as database, 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:

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

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
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 repositories by using the -r option when changing their password with the passwd(1) command.

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Evolving

kdestroy (1), kinit (1), kpasswd (1), passwd (1), syslog (3C), 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), pam.conf (5), attributes (7), kerberos (7), krb5envvar (7), ktkt_warnd (8) The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.

On successful acquisition of initial credentials (ticket-granting ticket), ktkt_warnd(8) will be notified, to alert the user when the initial credentials are about to expire.