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

4 files changed, 170 insertions, 2 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index 0e82ce8a9b..075cec8c71 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -1378,7 +1378,8 @@ struct plugin_interface {
 #define PLUGIN_INTERFACE_KADM5_HOOK  1
 #define PLUGIN_INTERFACE_CLPREAUTH   2
 #define PLUGIN_INTERFACE_KDCPREAUTH  3
-#define PLUGIN_NUM_INTERFACES        4
+#define PLUGIN_INTERFACE_CCSELECT    4
+#define PLUGIN_NUM_INTERFACES        5
 
 /* Retrieve the plugin module of type interface_id and name modname,
  * storing the result into module. */
@@ -1418,6 +1419,7 @@ struct _kdb5_dal_handle;        /* private, in kdb5.h */
 typedef struct _kdb5_dal_handle kdb5_dal_handle;
 struct _kdb_log_context;
 typedef struct krb5_preauth_context_st krb5_preauth_context;
+struct ccselect_module_handle;
 struct _krb5_context {
     krb5_magic      magic;
     krb5_enctype    *in_tkt_etypes;
@@ -1458,6 +1460,9 @@ struct _krb5_context {
     /* preauth module stuff */
     krb5_preauth_context *preauth_context;
 
+    /* cache module stuff */
+    struct ccselect_module_handle **ccselect_handles;
+
     /* error detail info */
     struct errinfo err;
 
diff --git a/src/include/k5-trace.h b/src/include/k5-trace.h
index 9b4c6095bd..8bf88e417b 100644
--- a/src/include/k5-trace.h
+++ b/src/include/k5-trace.h
@@ -119,7 +119,29 @@
 #define TRACE_CC_STORE_TKT(c, cache, creds)                             \
     TRACE(c, (c, "Also storing {creds} based on ticket", creds))
 
-#define TRACE_FAST_ARMOR_CCACHE(c, ccache_name)                 \
+#define TRACE_CCSELECT_VTINIT_FAIL(c, ret)                              \
+    TRACE(c, (c, "ccselect module failed to init vtable: {kerr}", ret))
+#define TRACE_CCSELECT_INIT_FAIL(c, name, ret)                          \
+    TRACE(c, (c, "ccselect module {str} failed to init: {kerr}", name, ret))
+#define TRACE_CCSELECT_MODCHOICE(c, name, server, cache, princ)         \
+    TRACE(c, (c, "ccselect module {str} chose cache {ccache} with client " \
+              "principal {princ} for server principal {princ}", name, cache, \
+              princ, server))
+#define TRACE_CCSELECT_MODNOTFOUND(c, name, server, princ)              \
+    TRACE(c, (c, "ccselect module {str} chose client principal {princ} " \
+              "for server principal {princ} but found no cache", name, princ, \
+              server))
+#define TRACE_CCSELECT_MODFAIL(c, name, ret, server)                    \
+    TRACE(c, (c, "ccselect module {str} yielded error {kerr} for server " \
+              "principal {princ}", name, ret, server))
+#define TRACE_CCSELECT_NOTFOUND(c, server)                           \
+    TRACE(c, (c, "ccselect can't find appropriate cache for server " \
+              "principal {princ}", server))
+#define TRACE_CCSELECT_DEFAULT(c, cache, server)                        \
+    TRACE(c, (c, "ccselect choosing default cache {ccache} for server " \
+              "principal {princ}", cache, server))
+
+#define TRACE_FAST_ARMOR_CCACHE(c, ccache_name) \
     TRACE(c, (c, "FAST armor ccache: {str}", ccache_name))
 #define TRACE_FAST_ARMOR_CCACHE_KEY(c, keyblock)                        \
     TRACE(c, (c, "Armor ccache sesion key: {keyblock}", keyblock))
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.