pam_krb5(5)

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES

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, /usr/lib/security/pam_krb5.so.1, provides functionality for all four PAM modules: authentication, account management, session management, and password management. The pam_krb5.so.1 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 refresh the Kerberos credentials cache, pam_sm_setcred(). pam_sm_authenticate() authenticates a user principal though the Kerberos authentication service. If the authentication request is successful, the authentication service sends a ticket-granting ticket (tgt) back to the pam_krb5.so.1 module, which then verifies that the TGT came from a valid 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, host/hostname.com@REALM where 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). Once the TGT is verified, it is stored in the credentials cache for later use by Kerberized network applications. If the host entry is not found in the keytab file, the authentication fails.

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

acceptor

Prevents the PAM module from performing the authentication service exchange used to obtain the initial ticket-granting ticket. This should be used on Kerberos application servers since the initial ticket is not needed.

debug

Provides syslog(3C) debugging information at LOG_DEBUG level.

nowarn

Turns off warning messages.

use_first_pass

Requests Kerberos V5 authentication with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If Kerberos V5 authentication fails, or if no password has been entered, it quits and does not prompt the user for a password. This option should only be used if the authentication service is designated as optional in the pam.conf configuration file.

try_first_pass

Requests Kerberos V5 authentication with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If Kerberos V5 authentication fails, or if no password has been entered, the user is prompted for a password with the prompt "Kerberos Password:".

use_xfn_pass

Requests Kerberos V5 authentication with a mapped password that has been stored under XFN. If Kerberos V5 authentication fails, or if no password has been entered, it quits and does not prompt the user for a password. This option should only be used if the authentication service is designated as optional in the pam.conf configuration file.

try_xfn_Pass

Requests Kerberos V5 authentication with a mapped password that has been stored under XFN. If Kerberos V5 authentication fails, or if no password has been stored, the user is prompted for a password with the prompt "Kerberos Password:".

Kerberos V5 Account Management Module

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 service module:

debug

Provides syslog(3C) debugging information at LOG_DEBUG level

nowarn

Turn off warning messages.

Kerberos V5 Session Management Module

The Kerberos V5 session management component provides functions to initiate pam_sm_open_session() and terminate pam_sm_close_session() Kerberos V5 sessions. For Kerberos V5, pam_sm_open_session is a null function. pam_close_session destroys a principal's credential cache as well as the kernel Kerberos credentials if the session being closed is the last open session on this server for the calling principal.

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 options can be passed in to the Kerberos V5 password module:

debug

Provides syslog(3C) debugging information at LOG_DEBUG level.

nowarn

Turns off warning messages.

use_first_pass

Requests Kerberos V5 authentication with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If Kerberos V5 authentication fails, or if no password has been entered, it quits and does not prompt the user for a password. If authentication succeeds, the user is prompted by "New KRB5 password:" for a new password. The user is then prompted a second time for the new password for verification and the KDC database is updated with the new password if both responses match.

try_first_pass

Requests Kerberos V5 authentication with the user's initial password (entered when the user authenticated to the first authentication module in the stack). If Kerberos V5 authentication fails, or if no password has been entered, the user is prompted for a password with the prompt "Old KRB5 Password:". If authentication succeeds, the user is prompted by "New KRB5 password:" for a new password. The user is then prompted a second time for the new password for verification and the KDC database is updated with the new password if both responses match.

use_xfn_pass

Requests Kerberos V5 authentication with a mapped password that has been stored under XFN. If Kerberos V5 authentication fails, or if no password has been stored, it quits and does not prompt the user for a password. If authentication succeeds, the user is prompted by "New KRB5 password:" for a new password. The user is then prompted a second time for the new password for verification and the KDC database is updated with the new password if both responses match.

try_xfn_pass

Requests Kerberos V5 authentication with a mapped password that has been stored under XFN. If Kerberos V5 authentication fails, or if no password has been stored, the user is prompted for a password with the prompt "Old KRB5 Password:". If authentication succeeds, the user is prompted by "New KRB5 password:" for a new password. The user is then prompted a second time for the new password for verification and the KDC database is updated with the new password if both responses match.

Sample pam.conf File

The following is a sample pam.conf configuration file with Kerberos V5 support. Please note that this is only intended to give the flavor of the pam.conf Kerberos V5 entries and is not complete.

#
# Authentication management
#
login auth required /usr/lib/security/$ISA/pam_unix.so.1 
login auth optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass
#
# Account management
#
dtlogin  account required  /usr/lib/security/$ISA/pam_unix.so.1
dtlogin  account optional  /usr/lib/security/$ISA/pam_krb5.so.1
#
# Session management
#
other  session required  /usr/lib/security/$ISA/pam_unix.so.1
other  session optional  /usr/lib/security/$ISA/pam_krb5.so.1
#
# Password management
#
other password required /usr/lib/security/$ISA/pam_unix.so.1
other password optional /usr/lib/security/$ISA/pam_krb5.so.1 try_first_pass

The Kerberos V5 module entries typically follow the Unix module entries. Thus, the Kerberos V5 modules are "stacked" behind the Unix module. For the login service, the Kerberos V5 authentication module runs after the Unix module. Its entry is optional, so the user can still login if it fails, assuming that the previous Unix module succeeded. If the entry designates required instead of optional, the user cannot login if Kerberos V5 authentication fails. Because the try_first_pass option is designated, it tries the user's password entered for the Unix module. If Kerberos V5 authentication fails, or no password has been entered, the user is prompted for the Kerberos V5 password. For all session related services, the Kerberos V5 session module runs after the Unix module. For the dtlogin service, the Kerberos V5 account management module runs after the Unix module. For all password changing related services, the Kerberos V5 module runs after the Unix module. Because the try_first_pass option is designated, if the initial password entered for the Unix module authenticates Kerberos V5 successfully, the old Kerberos V5 password is not requested from the user; only the new Kerberos V5 password is requested.

ATTRIBUTES

See attributes(5) for description of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT Level	MT-Safe with exceptions
Interface Stability	Evolving

SEE ALSO

keylogin(1), ktutil(1), pam(3PAM), pam_authenticate(3PAM), syslog(3C), libpam(3LIB), pam.conf(4), attributes(5), SEAM(5), pam_authtok_check(5), pam_authtok_get(5), pam_authtok_store(5), pam_dhkeys(5), pam_passwd_auth(5), pam_unix(5), pam_unix_account(5), pam_unix_auth(5), pam_unix_session(5)

NOTES

The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.

The pam_unix(5) module might not be supported in a future release. Similar functionality is provided by pam_authtok_check(5), pam_authtok_get(5), pam_authtok_store(5), pam_dhkeys(5), pam_passwd_auth(5), pam_unix_account(5), pam_unix_auth(5), and pam_unix_session(5).

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | SEE ALSO | NOTES