Add _with_password credential acquisition functions to KIM API

Needed for kinit password option.

ticket: new

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20963 dc483132-0cff-0310-8789-dd5450dbe970

2 files changed, 76 insertions, 3 deletions

diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h
index 709c69814..a1cba1710 100644
--- a/src/include/kim/kim_ccache.h
+++ b/src/include/kim/kim_ccache.h
@@ -114,6 +114,12 @@ extern "C" {
  * It can be trivially implemented using 
  * #kim_ccache_create_from_client_identity() and #kim_ccache_create_new().  
  *
+ * For legacy password-based Kerberos environments KIM also provides
+ * #kim_ccache_create_new_with_password() and 
+ * #kim_ccache_create_new_if_needed_with_password().  You should not use these 
+ * functions unless you know that they will only be used in environments using 
+ * passwords.  Otherwise users without passwords may be prompted for them.
+ *
  * KIM provides the #kim_ccache_create_from_keytab() to create credentials 
  * using a keytab and store them in the cache collection. A keytab is an 
  * on-disk copy of a client identity's secret key.  Typically sites use 
@@ -301,7 +307,7 @@ void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator);
  * \param in_client_identity  a client identity to obtain a credential for.   Specify KIM_IDENTITY_ANY to 
  *                            allow the user to choose.
  * \param in_options          options to control credential acquisition. 
- * \note Depending on the kim_options specified, #kim_ccache_create_new() may 
+ * \note #kim_ccache_create_new() may 
  * present a GUI or command line prompt to obtain information from the user. 
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
  * \brief Acquire a new initial credential and store it in a ccache.
@@ -311,11 +317,32 @@ kim_error kim_ccache_create_new (kim_ccache          *out_ccache,
                                  kim_options          in_options);
 
 /*!
+ * \param out_ccache          on exit, a new cache object for a ccache containing a newly acquired 
+ *      		      initial credential.  Must be freed with kim_ccache_free().
+ * \param in_client_identity  a client identity to obtain a credential for.   Specify KIM_IDENTITY_ANY to 
+ *                            allow the user to choose.
+ * \param in_options          options to control credential acquisition. 
+ * \param in_password         a password to be used while obtaining credentials. 
+ * \note #kim_ccache_create_new_with_password() exists to support
+ * legacy password-based Kerberos environments.  You should not use this 
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \brief Acquire a new initial credential and store it in a ccache
+ * using the provided password..
+ */
+kim_error kim_ccache_create_new_with_password (kim_ccache   *out_ccache,
+                                               kim_identity  in_client_identity,
+                                               kim_options   in_options,
+                                               kim_string    in_password);
+
+/*!
  * \param out_ccache          on exit, a ccache object for a ccache containing a newly acquired   
  *                            initial credential. Must be freed with kim_ccache_free().
  * \param in_client_identity  a client identity to obtain a credential for.
  * \param in_options          options to control credential acquisition (if a credential is acquired). 
- * \note Depending on the kim_options specified, #kim_ccache_create_new_if_needed() may 
+ * \note #kim_ccache_create_new_if_needed() may 
  * present a GUI or command line prompt to obtain information from the user. 
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
  * \brief Find a ccache containing a valid initial credential in the cache collection, or if
@@ -326,6 +353,26 @@ kim_error kim_ccache_create_new_if_needed (kim_ccache   *out_ccache,
                                            kim_options   in_options);
 
 /*!
+ * \param out_ccache          on exit, a ccache object for a ccache containing a newly acquired   
+ *                            initial credential. Must be freed with kim_ccache_free().
+ * \param in_client_identity  a client identity to obtain a credential for.
+ * \param in_options          options to control credential acquisition (if a credential is acquired). 
+ * \param in_password         a password to be used while obtaining credentials. 
+ * \note #kim_ccache_create_new_if_needed_with_password() exists to support
+ * legacy password-based Kerberos environments.  You should not use this 
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \brief Find a ccache containing a valid initial credential in the cache collection, or if
+ *        unavailable, acquire and store a new initial credential using the provided password.
+ */
+kim_error kim_ccache_create_new_if_needed_with_password (kim_ccache   *out_ccache,
+                                                         kim_identity  in_client_identity,
+                                                         kim_options   in_options,
+                                                         kim_string    in_password);
+
+/*!
  * \param out_ccache          on exit, a ccache object for a ccache containing a TGT  
  *                            credential. Must be freed with kim_ccache_free().
  * \param in_client_identity  a client identity to find a ccache for.  If 
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h
index e1303aeca..c061f1199 100644
--- a/src/include/kim/kim_credential.h
+++ b/src/include/kim/kim_credential.h
@@ -101,6 +101,11 @@ typedef int kim_credential_state;
  * kim_options specified, #kim_credential_create_new() may present a 
  * GUI or command line prompt to obtain information from the user.
  *
+ * For legacy password-based Kerberos environments KIM also provides
+ * #kim_credential_create_new_with_password().  You should not use this 
+ * function unless you know that it will only be used in environments using 
+ * passwords.  Otherwise users without passwords may be prompted for them.
+ *
  * KIM provides the #kim_credential_create_from_keytab() to create credentials 
  * using a keytab. A keytab is an on-disk copy of a client identity's secret 
  * key.  Typically sites use keytabs for client identities that identify a 
@@ -324,7 +329,7 @@ void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterat
  * \param in_client_identity  a client identity to obtain a credential for.   Specify NULL to 
  *                            allow the user to choose the identity
  * \param in_options          options to control credential acquisition. 
- * \note Depending on the kim_options specified, #kim_credential_create_new() may 
+ * \note #kim_credential_create_new() may 
  * present a GUI or command line prompt to obtain information from the user. 
  * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
  * \brief Acquire a new initial credential.
@@ -335,6 +340,27 @@ kim_error kim_credential_create_new (kim_credential *out_credential,
                                      kim_options     in_options);
 
 /*!
+ * \param out_credential      on exit, a new credential object containing a newly acquired 
+ *                            initial credential.  Must be freed with kim_credential_free().
+ * \param in_client_identity  a client identity to obtain a credential for.   Specify NULL to 
+ *                            allow the user to choose the identity
+ * \param in_options          options to control credential acquisition. 
+ * \param in_password         a password to be used while obtaining the credential. 
+ * \note #kim_credential_create_new_with_password() exists to support
+ * legacy password-based Kerberos environments.  You should not use this 
+ * function unless you know that it will only be used in environments using passwords.
+ * This function may also present a GUI or command line prompt to obtain
+ * additional information needed to obtain credentials (eg: SecurID pin).
+ * \return On success, #KIM_NO_ERROR.  On failure, an error code representing the failure.
+ * \brief Acquire a new initial credential using the provided password.
+ * \sa kim_ccache_create_new
+ */
+kim_error kim_credential_create_new_with_password (kim_credential *out_credential,
+                                                   kim_identity    in_client_identity,
+                                                   kim_options     in_options,
+                                                   kim_string      in_password);
+    
+/*!
  * \param out_credential  on exit, a new credential object containing an initial credential
  *                        for \a in_identity obtained using \a in_keytab.  
  *                        Must be freed with kim_credential_free().