Add krb5_cc_select() API and pluggable interface

The interface has two built-in modules.  The realm module guesses a
cache based on the server realm if it is known.  The k5identity module
(Unix only) chooses a client principal based on rules in a .k5identity
file in the user's homedir.

ticket: 6957

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

2 files changed, 141 insertions, 0 deletions

diff --git a/src/include/krb5/ccselect_plugin.h b/src/include/krb5/ccselect_plugin.h
new file mode 100644
index 0000000000..ab3270bbda
--- /dev/null
+++ b/src/include/krb5/ccselect_plugin.h
@@ -0,0 +1,105 @@
+/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ * Copyright (C) 2011 by the 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.
+ */
+
+/*
+ * Declarations for credential cache selection module implementors.
+ *
+ * The ccselect pluggable interface currently has only one supported major
+ * version, which is 1.  Major version 1 has a current minor version number of
+ * 1.
+ *
+ * Password quality plugin modules should define a function named
+ * ccselect_<modulename>_initvt, matching the signature:
+ *
+ *   krb5_error_code
+ *   ccselect_modname_initvt(krb5_context context, int maj_ver, int min_ver,
+ *                           krb5_plugin_vtable vtable);
+ *
+ * The initvt function should:
+ *
+ * - Check that the supplied maj_ver number is supported by the module, or
+ *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
+ *
+ * - Cast the vtable pointer as appropriate for maj_ver:
+ *     maj_ver == 1: Cast to krb5_ccselect_vtable
+ *
+ * - Initialize the methods of the vtable, stopping as appropriate for the
+ *   supplied min_ver.  Optional methods may be left uninitialized.
+ *
+ * Memory for the vtable is allocated by the caller, not by the module.
+ */
+
+#ifndef KRB5_CCSELECT_PLUGIN_H
+#define KRB5_CCSELECT_PLUGIN_H
+
+#include <krb5/krb5.h>
+#include <krb5/plugin.h>
+
+/* An abstract type for password quality module data. */
+typedef struct krb5_ccselect_moddata_st *krb5_ccselect_moddata;
+
+#define KRB5_CCSELECT_PRIORITY_AUTHORITATIVE 2
+#define KRB5_CCSELECT_PRIORITY_HEURISTIC     1
+
+/*** Method type declarations ***/
+
+/*
+ * Mandatory: Initialize module data and set *priority_out to one of the
+ * KRB5_CCSELECT_PRIORITY constants above.  Authoritative modules will be
+ * consulted before heuristic ones.
+ */
+typedef krb5_error_code
+(*krb5_ccselect_init_fn)(krb5_context context, krb5_ccselect_moddata *data_out,
+                         int *priority_out);
+
+/*
+ * Mandatory: Select a cache based on a server principal.  Return 0 on success,
+ * with *cache_out set to the selected cache and *princ_out set to its default
+ * principal.  Return KRB5_PLUGIN_NO_HANDLE to defer to other modules.  Return
+ * KRB5_CC_NOTFOUND with *princ_out set if the client principal can be
+ * authoritatively determined but no cache exists for it.  Return other errors
+ * as appropriate.
+ */
+typedef krb5_error_code
+(*krb5_ccselect_choose_fn)(krb5_context context, krb5_ccselect_moddata data,
+                           krb5_principal server, krb5_ccache *cache_out,
+                           krb5_principal *princ_out);
+
+/* Optional: Release resources used by module data. */
+typedef void
+(*krb5_ccselect_fini_fn)(krb5_context context, krb5_ccselect_moddata data);
+
+/*** vtable declarations **/
+
+/* Password quality plugin vtable for major version 1. */
+typedef struct krb5_ccselect_vtable_st {
+    const char *name;           /* Mandatory: name of module. */
+    krb5_ccselect_init_fn init;
+    krb5_ccselect_choose_fn choose;
+    krb5_ccselect_fini_fn fini;
+    /* Minor version 1 ends here. */
+} *krb5_ccselect_vtable;
+
+#endif /* KRB5_CCSELECT_PLUGIN_H */
diff --git a/src/include/krb5/krb5.hin b/src/include/krb5/krb5.hin
index d1a7c83c61..049bf91f10 100644
--- a/src/include/krb5/krb5.hin
+++ b/src/include/krb5/krb5.hin
@@ -4453,6 +4453,42 @@ krb5_error_code KRB5_CALLCONV
 krb5_cc_cache_match(krb5_context context, krb5_principal client,
                     krb5_ccache *cache_out);
 
+/**
+ * Select a credential cache to use with a server principal.
+ *
+ * @param [in]  context         Library context
+ * @param [in]  server          Server principal
+ * @param [out] cache_out       Credential cache handle
+ * @param [out] princ_out       Client principal
+ *
+ * Select a cache within the collection containing credentials most appropriate
+ * for use with @a server, according to configured rules and heuristics.
+ *
+ * Use krb5_cc_close() to release @a cache_out when it is no longer needed.
+ * Use krb5_free_principal() to release @a princ_out when it is no longer
+ * needed.  Note that @a princ_out is set in some error conditions.
+ *
+ * @return
+ * If an appropriate cache is found, 0 is returned, @a cache_out is set to the
+ * selected cache, and @a princ_out is set to the default principal of that
+ * cache.
+ *
+ * If the appropriate client principal can be authoritatively determined but
+ * the cache collection contains no credentials for that principal, then
+ * KRB5_CC_NOTFOUND is returned, @a cache_out is set to NULL, and @a princ_out
+ * is set to the appropriate client principal.
+ *
+ * If no configured mechanism can determine the appropriate cache or principal,
+ * KRB5_CC_NOTFOUND is returned and @a cache_out and @a princ_out are set to
+ * NULL.
+ *
+ * Any other error code indicates a fatal error in the processing of a cache
+ * selection mechanism.
+ */
+krb5_error_code KRB5_CALLCONV
+krb5_cc_select(krb5_context context, krb5_principal server,
+               krb5_ccache *cache_out, krb5_principal *princ_out);
+
 /* krb5_free.c */
 /**
  * Free the storage assigned to a principal.