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

6 files changed, 79 insertions, 51 deletions

diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h
index 709c698142..a1cba17101 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 e1303aeca8..c061f1199b 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().
diff --git a/src/kim/lib/kim.exports b/src/kim/lib/kim.exports
index ca96d04a2d..0216e4be39 100644
--- a/src/kim/lib/kim.exports
+++ b/src/kim/lib/kim.exports
@@ -93,6 +93,7 @@ kim_credential_iterator_next
 kim_credential_iterator_free
 
 kim_credential_create_new
+kim_credential_create_new_with_password
 kim_credential_create_from_keytab
 kim_credential_create_from_krb5_creds
 kim_credential_copy
@@ -116,7 +117,9 @@ kim_ccache_iterator_next
 kim_ccache_iterator_free
 
 kim_ccache_create_new
+kim_ccache_create_new_with_password
 kim_ccache_create_new_if_needed
+kim_ccache_create_new_if_needed_with_password
 kim_ccache_create_from_client_identity
 kim_ccache_create_from_keytab
 kim_ccache_create_from_default
diff --git a/src/kim/lib/kim_ccache_private.h b/src/kim/lib/kim_ccache_private.h
deleted file mode 100644
index 6e1d7a12e3..0000000000
--- a/src/kim/lib/kim_ccache_private.h
+++ /dev/null
@@ -1,42 +0,0 @@
-/*
- * $Header$
- *
- * Copyright 2006 Massachusetts Institute of Technology.
- * All Rights Reserved.
- *
- * Export of this software from the United States of America may
- * require a specific license from the United States Government.
- * It is the responsibility of any person or organization contemplating
- * export to obtain such a license before exporting.
- *
- * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
- * distribute this software and its documentation for any purpose and
- * without fee is hereby granted, provided that the above copyright
- * notice appear in all copies and that both that copyright notice and
- * this permission notice appear in supporting documentation, and that
- * the name of M.I.T. not be used in advertising or publicity pertaining
- * to distribution of the software without specific, written prior
- * permission.  Furthermore if you modify this software you must label
- * your software as modified software and not distribute it in such a
- * fashion that it might be confused with the original M.I.T. software.
- * M.I.T. makes no representations about the suitability of
- * this software for any purpose.  It is provided "as is" without express
- * or implied warranty.
- */
-
-#ifndef KIM_CCACHE_PRIVATE_H
-#define KIM_CCACHE_PRIVATE_H
-
-#include <kim/kim.h>
-
-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);
-
-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);
-
-#endif /* KIM_CCACHE_PRIVATE_H */
diff --git a/src/kim/lib/kim_credential_private.h b/src/kim/lib/kim_credential_private.h
index c9a975d59e..3f30d6c738 100644
--- a/src/kim/lib/kim_credential_private.h
+++ b/src/kim/lib/kim_credential_private.h
@@ -36,9 +36,4 @@ kim_error kim_credential_create_for_change_password (kim_credential  *out_creden
                                                      kim_ui_context  *in_ui_context,
                                                      kim_boolean     *out_user_was_prompted);
 
-kim_error kim_credential_create_new_with_password (kim_credential *out_credential,
-                                                   kim_identity    in_identity,
-                                                   kim_options     in_options,
-                                                   kim_string      in_password);
-
 #endif /* KIM_CREDENTIAL_PRIVATE_H */
diff --git a/src/kim/lib/kim_private.h b/src/kim/lib/kim_private.h
index 7a86d7e0a9..939279f77c 100644
--- a/src/kim/lib/kim_private.h
+++ b/src/kim/lib/kim_private.h
@@ -39,7 +39,6 @@
 #include "kim_debug_private.h"
 #include "kim_error_private.h"
 #include "kim_identity_private.h"
-#include "kim_ccache_private.h"
 #include "kim_credential_private.h"
 #include "kim_options_private.h"
 #include "kim_preferences_private.h"