I've attached updated pam_krb5.5 and pam_krb5.5.diffmarked. On Mon, Dec 14, 2009 at 05:42:23PM -0600, Will Fiveash wrote: > On Mon, Dec 14, 2009 at 02:52:51PM -0800, Gary Winiger wrote: > > > The final spec and man page for the pam_krb5 pkinit project > > > have been put into the case directory. If there are no > > > further objections, this case should get approved at the meeting > > > this week. > > > > From message 60 of 17 Nov and not yet answered: > > > > Gary.. > > ====== > > >From pkinit-final: > > > > "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 passwd is NULL > > - the old passwd is NULL > > - verification of the old passwd 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 app 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." > > > > This information does not seem to be in the man page. How does the > > administrator know it? > > I will update the man page to include this. > > > Not being a pkinit expert, I'd like to understand how the password > > stack will know if the user was authenticated by pkinit? > > A field in the krb module data struct will indicate this. > > > I feel TCR strong that the man page needs to be complete relative to this > > part of the spec. I'm also concerned that pam_krb5 in the password stack > > won't likely be called without PAM_AUTHTOK or PAM_OLDAUTHTOK set. > > I am not changing the conditions under which pam_krb5 pam_sm_chauthtok() > is being called, only it's behavior if pam_krb5 did PKINIT using a PIN > (not the PAM_AUTHTOK password) in the auth stack. > > > Which call to pam_sm_chauthtok() PAM_PRELIM_CHECK and/or PAM_UPDATE_AUTHTOK > > will be making these checks? > > The checks are made if the PAM_UPDATE_AUTHTOK flag is set. The project > is not changing the behavior of pam_sm_chauthtok() if the > PAM_PRELIM_CHECK flag is set which is to return PAM_IGNORE. > > -- > Will Fiveash > Sun Microsystems Office x64079/512-401-1079 > Austin, TX, 78727 (TZ=CST6CDT), USA > Internal Solaris Kerberos/GSS/SASL website: http://kerberos.sfbay.sun.com > http://opensolaris.org/os/project/kerberos/
-- Will Fiveash Sun Microsystems Office x64079/512-401-1079 Austin, TX, 78727 (TZ=CST6CDT), USA Internal Solaris Kerberos/GSS/SASL website: http://kerberos.sfbay.sun.com http://opensolaris.org/os/project/kerberos/ -------------- next part -------------- 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 "pkinit" module option is set the Kerberos V5 authentication module will try to do PKINIT authentication if both the system and the KDC are configured to support this type of authentication. This form of authentication uses a user's certificate and private key to acquire the user's initial Kerberos credential (TGT). Note that one of the keystore formats supported is PKCS11 which supports use of any PKCS11 compatible keystore capable of storing the required credential and private key needed for PKINIT authentication (PKCS11 compatible smartcards are an example). See krb5.conf(4) for more details on PKINIT configuration. Also note that this form of authentication 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. If pam_sm_authenticate() is called and the "pkinit" module option is not set then the Kerberos V5 authentication module will do password based authentication. In either case, 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 in the auth stack, the Kerberos V5 authentication module will use that PAM_AUTHTOK password for either PKINIT or password based Kerberos authentication. If the PAM_USER item is not set pam_krb5 with the "pkinit" option will prompt for and set that item. If the PAM_AUTHTOK password item has not been set when pam_sm_authenticate() is called, which is the case when pam_krb5 is stacked before pam_authtok_get in the auth stack, and the "pkinit" option is present the Kerberos V5 authentication module will allow the Kerberos pkinit preauth plugin to prompt for whatever information is needed to perform PKINIT (typically this will be for the user's PIN). No PAM items are set via this prompting. See krb5.conf(5) for more information on PKINIT configuration options. If it is desirable to initially have the Kerberos V5 authentication module try PKINIT Kerberos authentication and fall back to password based Kerberos authentication then either the sufficient or optional control flags must be provided for the instance of pam_krb5 with the "pkinit" module option set and another instance of pam_krb5 without the "pkinit" module option 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 with the "pkinit" module option set 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. pkinit Indicates that the Kerberos V5 authentication module should try Kerberos PKINIT authentication instead of the default password based Kerberos authentication. 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. Note that if the Kerberos V5 authentication module used PKINIT authentication in the auth stack then the Kerberos V5 password management module will return PAM_IGNORE in the following cases: - The new password is NULL. - The old password is NULL. - Verification of the old password fails. The rational behind this is that the KDC may not allow a PKINIT user to change/set a password since the user may be expected to use PKINIT only. If all of the cases above are false the Kerberos V5 password management module will try to change the user's password in the KDC database. Note, if the KDC only supports PKINIT authentication then the Kerberos V5 password management module should not be present in any password stacks. Related to PKINIT the Kerberos V5 password management module does not support changing the key store PIN used to access a user's private key and certificate. 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 using password based authentication 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 using password based authentication 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 using password based authentication 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 pkinit 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 authentication. login auth required pam_unix_cred.so.1 login auth required pam_krb5.so.1 pkinit Example 6: Authenticate Users Through Kerberos PKINIT Optionally The following example allows users to acquire a Kerberos credential using PKINIT authentication 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 pkinit 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 authentication 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 pkinit login auth requisite pam_authtok_get.so.1 login auth required pam_unix_auth.so.1 Example 8: Authenticate Users Through Kerberos PKINIT as a requirement using the PAM_AUTHTOK password. The following example allows users to login using their PAM_AUTHTOK password acquired by pam_authtok_get. This password would be used by pam_krb5 to try PKINIT authentication and would also be used by pam_unix_auth to authenticate the user via the user's Unix account. If PKINIT requires a password/PIN that differs from the user's Unix password then pam_krb5 must be stacked above pam_authtok_get. login auth required pam_unix_cred.so.1 login auth requisite pam_authtok_get.so.1 login auth required pam_krb5.so.1 pkinit login auth required pam_unix_auth.so.1 Example 9: 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 authentication or using password based authentication 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 authentication 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 pkinit login auth requisite pam_authtok_get.so.1 login auth required pam_krb5.so.1 Example 10: 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 authentication or using password based authentication if PKINIT fails. Note, if pam_krb5 PKINIT succeeds, the second instance of pam_krb5 will not try password authentication and will just return ignore. If pam_krb5 PKINIT fails the second instance of pam_krb5 will try password based authentication and return success or failure. login auth required pam_unix_cred.so.1 login auth optional pam_krb5.so.1 pkinit 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 11: 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 authentication 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 pkinit 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 -------------- next part -------------- --- pam_krb5_man_orig Mon Dec 14 19:47:10 2009 +++ pam_krb5_man_pkinit Mon Dec 14 19:49:41 2009 @@ -1,657 +1,863 @@ 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 + "pkinit" module option is set the Kerberos V5 authentication + module will try to do PKINIT authentication if both the + system and the KDC are configured to support this type of + authentication. This form of authentication uses a user's + certificate and private key to acquire the user's initial + Kerberos credential (TGT). Note that one of the keystore + formats supported is PKCS11 which supports use of any PKCS11 + compatible keystore capable of storing the required + credential and private key needed for PKINIT authentication + (PKCS11 compatible smartcards are an example). See + krb5.conf(4) for more details on PKINIT configuration. Also + note that this form of authentication 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. + If pam_sm_authenticate() is called and the "pkinit" module + option is not set then the Kerberos V5 authentication module + will do password based authentication. + + In either case, 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 in the auth + stack, the Kerberos V5 authentication module will use that + PAM_AUTHTOK password for either PKINIT or password based + Kerberos authentication. + + If the PAM_USER item is not set pam_krb5 with the "pkinit" + option will prompt for and set that item. + + If the PAM_AUTHTOK password item has not been set when + pam_sm_authenticate() is called, which is the case when + pam_krb5 is stacked before pam_authtok_get in the auth + stack, and the "pkinit" option is present the Kerberos V5 + authentication module will allow the Kerberos pkinit preauth + plugin to prompt for whatever information is needed to + perform PKINIT (typically this will be for the user's PIN). + No PAM items are set via this prompting. See krb5.conf(5) + for more information on PKINIT configuration options. + + If it is desirable to initially have the Kerberos V5 + authentication module try PKINIT Kerberos authentication and + fall back to password based Kerberos authentication then + either the sufficient or optional control flags must be + provided for the instance of pam_krb5 with the "pkinit" + module option set and another instance of pam_krb5 without + the "pkinit" module option 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 with the "pkinit" module option set 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. + pkinit Indicates that the Kerberos V5 authentication + module should try Kerberos PKINIT authentication + instead of the default password based Kerberos + authentication. + 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): + Distribution Center (KDC) database. + Note that if the Kerberos V5 authentication module used + PKINIT authentication in the auth stack then the Kerberos V5 + password management module will return PAM_IGNORE in the + following cases: + + - The new password is NULL. + - The old password is NULL. + - Verification of the old password fails. + + The rational behind this is that the KDC may not allow a + PKINIT user to change/set a password since the user may be + expected to use PKINIT only. If all of the cases above are + false the Kerberos V5 password management module will try to + change the user's password in the KDC database. + + Note, if the KDC only supports PKINIT authentication then + the Kerberos V5 password management module should not be + present in any password stacks. + + Related to PKINIT the Kerberos V5 password management module + does not support changing the key store PIN used to access a + user's private key and certificate. + + 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 authentication 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 authentication 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 authentication 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 pkinit + 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 authentication. + + login auth required pam_unix_cred.so.1 + login auth required pam_krb5.so.1 pkinit + + Example 6: Authenticate Users Through Kerberos PKINIT Optionally + + The following example allows users to acquire a Kerberos + credential using PKINIT authentication 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 pkinit + 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 + authentication 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 pkinit + login auth requisite pam_authtok_get.so.1 + login auth required pam_unix_auth.so.1 + + Example 8: Authenticate Users Through Kerberos PKINIT as a + requirement using the PAM_AUTHTOK password. + + The following example allows users to login using their + PAM_AUTHTOK password acquired by pam_authtok_get. This + password would be used by pam_krb5 to try PKINIT + authentication and would also be used by pam_unix_auth to + authenticate the user via the user's Unix account. If PKINIT + requires a password/PIN that differs from the user's Unix + password then pam_krb5 must be stacked above pam_authtok_get. + + login auth required pam_unix_cred.so.1 + login auth requisite pam_authtok_get.so.1 + login auth required pam_krb5.so.1 pkinit + login auth required pam_unix_auth.so.1 + + Example 9: 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 authentication or using password + based authentication 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 authentication 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 pkinit + login auth requisite pam_authtok_get.so.1 + login auth required pam_krb5.so.1 + + Example 10: 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 authentication or using password + based authentication if PKINIT fails. Note, if pam_krb5 + PKINIT succeeds, the second instance of pam_krb5 will not try + password authentication and will just return ignore. If + pam_krb5 PKINIT fails the second instance of pam_krb5 will + try password based authentication and return success or + failure. + + login auth required pam_unix_cred.so.1 + login auth optional pam_krb5.so.1 pkinit + 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 11: 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 authentication 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 pkinit + 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
