Add new cache collection APIs

* krb5_cc_get_full_name retrieves the full type:name of a cache.
* krb5_cc_switch makes a cache the primary cache.
* krb5_cc_cache_match searches the collection for a client principal.
* krb5_free_string releases a string (for the krb5_cc_get_full_name
  result).

All of these are from Heimdal except for krb5_free_string (Heimdal uses
krb5_xfree).

ticket: 6954

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

2 files changed, 70 insertions, 0 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index c153a7e51..0e82ce8a9 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -2367,6 +2367,7 @@ struct _krb5_cc_ops {
                                                 krb5_timestamp *);
     krb5_error_code (KRB5_CALLCONV *lock)(krb5_context, krb5_ccache);
     krb5_error_code (KRB5_CALLCONV *unlock)(krb5_context, krb5_ccache);
+    krb5_error_code (KRB5_CALLCONV *switch_to)(krb5_context, krb5_ccache);
 };
 
 extern const krb5_cc_ops *krb5_cc_dfl_ops;
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index e594035bb..d1a7c83c6 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -2285,6 +2285,18 @@ typedef struct _krb5_cccol_cursor *krb5_cccol_cursor;
 const char * KRB5_CALLCONV
 krb5_cc_get_name(krb5_context context, krb5_ccache cache);
 
+/*
+ * Retrieve the full name of a credential cache.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  cache           Credential cache handle
+ * @param [out] fullname_out    Full name of cache
+ *
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_get_full_name(krb5_context context, krb5_ccache cache,
+                      char **fullname_out);
+
 #if KRB5_DEPRECATED
 krb5_error_code KRB5_CALLCONV
 krb5_cc_gen_new(krb5_context context, krb5_ccache *cache);
@@ -4393,6 +4405,54 @@ krb5_cc_set_config(krb5_context context, krb5_ccache id,
 krb5_boolean KRB5_CALLCONV
 krb5_is_config_principal(krb5_context context, krb5_const_principal principal);
 
+/**
+ * Make a credential cache the primary cache for its collection.
+ *
+ * @param [in] context          Library context
+ * @param [in] cache            Credential cache handle
+ *
+ * If the type of @a cache supports it, set @a cache to be the primary
+ * credential cache for the collection it belongs to.
+ *
+ * @retval
+ * 0  Success, or the type of @a cache doesn't support switching
+ * @return
+ * Kerberos error codes
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_switch(krb5_context context, krb5_ccache cache);
+
+/**
+ * Determine whether a credential cache type supports switching.
+ *
+ * @param [in] context          Library context
+ * @param [in] type             Credential cache type
+ *
+ * @retval @c TRUE if @a type supports switching
+ * @retval @a FALSE if it does not or is not a valid credential cache type.
+ */
+krb5_boolean KRB5_CALLCONV
+krb5_cc_support_switch(krb5_context context, const char *type);
+
+/**
+ * Find a credential cache with a specified client principal.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  client          Client principal
+ * @param [out] cache_out       Credential cache handle
+ *
+ * Find a cache within the collection whose default principal is @a client.
+ * Use @a krb5_cc_close to close @a ccache when it is no longer needed.
+ *
+ * @retval 0 Success
+ * @retval KRB5_CC_NOTFOUND
+ *
+ * @sa krb5_cccol_cursor_new
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_cache_match(krb5_context context, krb5_principal client,
+                    krb5_ccache *cache_out);
+
 /* krb5_free.c */
 /**
  * Free the storage assigned to a principal.
@@ -4571,6 +4631,15 @@ void KRB5_CALLCONV
 krb5_free_unparsed_name(krb5_context context, char *val);
 
 /**
+ * Free a string allocated by a krb5 function.
+ *
+ * @param [in] context          Library context
+ * @param [in] val              String to be freed
+ */
+void KRB5_CALLCONV
+krb5_free_string(krb5_context context, char *val);
+
+/**
  * Free an array of checksum types.
  *
  * @param [in] context          Library context