Template Version: @(#)sac_nextcase 1.68 02/23/09 SMI
This information is Copyright 2009 Sun Microsystems
1. Introduction
    1.1. Project/Component Working Name:
	 pam_krb5 PKINIT support
    1.2. Name of Document Author/Supplier:
	 Author:  Will Fiveash
    1.3  Date of This Document:
     December 10, 2009

4. Technical Description

pam_krb5 PKINIT support
--------------------------------------

Recently support for public key based initial Kerberos credential
acquisition or PKINIT was added to Solaris Kerberos (see PSARC
2008/631).  What I propose now is modifying pam_krb5 in the following
way to take advantage of this PKINIT support and essentially allow a
user to use a smartcard or other form of pubic/private keys to acquire
their Kerberos credential without using their long term Kerberos
password.

The pam_krb5 authentication module will be modified to support a new
module option, "pkinit", which if present on the auth stack instance of
pam_krb5 indicates that pam_krb5 should do PKINIT preauth.  If
PAM_AUTHTOK is set then pam_krb5 would try PKINIT preauth using that
password.  If PAM_AUTHTOK is not set then pam_krb5 would call the
Kerberos library passing a prompter function that would allow the
Kerberos pkinit preauth plugin to prompt for whatever information is
required to access the user's private key via the PAM_CONV conversation
function.  In either case if PKINIT fails to acquire a Kerberos
credential a PAM error would be returned.

The pam_krb5 authentication module will support being stacked two times
in the auth stack to support a "fall back to password based Kerberos
preauth" scenario.  The second instance of the pam_krb5 auth module in a
auth stack would check if the previous instance of the pam_krb5 auth
module returned PAM_SUCCESS and if so would immediately return
PAM_IGNORE.  If the previous instance did not return PAM_SUCCESS then
the pam_krb5 auth module would try password based Kerberos preauth and
return PAM_SUCCESS if a valid Kerberos credential was acquired.

The pam_krb auth module, when doing PKINIT, will prompt for and set
PAM_USER if that item is not already set in the auth stack.

The pam_krb5 password module will change in that if PKINIT
authentication was done it will return PAM_IGNORE in the following
cases:

- the new password is NULL
- the old password is NULL
- verification of the old password fails.

If none of the above is true then pam_krb tries to change the password
and will return an error if that fails.  The rational behind this is if
some PAM module causes pam_acct_mgmt() to return PAM_NEW_AUTHTOK_REQD
and/or the application subsequently calls pam_chauthtok(), pam_krb5 will
change a user's password.  But this may well fail: the KDC may not want
to allow a PKINIT user to change/set a password since the user may be
expected to use PKINIT.

The other pam_krb5 modules (account and session) will not change.

INTERFACE STABILITY AND RELEASE BINDINGS
----------------------------------------

Interface		Stability		Release Binding

new pam_krb5 option	Committed		Minor


6. Resources and Schedule
    6.4. Steering Committee requested information
   	6.4.1. Consolidation C-team Name: ON
    6.5. ARC review type: FastTrack
    6.6. ARC Exposure: open