+/*** Plugin framework ***/
+
+/*
+ * This framework can be used to create pluggable interfaces. Not all existing
+ * pluggable interface use this framework, but new ones should. A new
+ * pluggable interface entails:
+ *
+ * - An interface ID definition in the list of #defines below.
+ *
+ * - A name in the interface_names array in lib/krb5/krb/plugins.c.
+ *
+ * - An installed public header file in include/krb5. The public header should
+ * include <krb5/plugin.h> and should declare a vtable structure for each
+ * supported major version of the interface.
+ *
+ * - A consumer API implementation, located within the code unit which makes
+ * use of the pluggable interface. The consumer API should consist of:
+ *
+ * . An interface-specific handle type which contains a vtable structure for
+ * the module (or a union of several such structures, if there are multiple
+ * supported major versions) and, optionally, resource data bound to the
+ * handle.
+ *
+ * . An interface-specific loader function which creates a handle or list of
+ * handles. A list of handles would be created if the interface is a
+ * one-to-many interface where the consumer wants to consult all available
+ * modules; a single handle would be created for an interface where the
+ * consumer wants to consult a specific module. The loader function should
+ * use k5_plugin_load or k5_plugin_load_all to produce one or a list of
+ * vtable initializer functions, and should use those functions to fill in
+ * the vtable structure for the module (if necessary, trying each supported
+ * major version starting from the most recent). The loader function can
+ * also bind resource data into the handle based on caller arguments, if
+ * appropriate.
+ *
+ * . For each plugin method, a wrapper function which accepts a krb5_context,
+ * a plugin handle, and the method arguments. Wrapper functions should
+ * invoke the method function contained in the handle's vtable.
+ *
+ * - Possibly, built-in implementations of the interface, also located within
+ * the code unit which makes use of the interface. Built-in implementations
+ * must be registered with k5_plugin_register before the first call to
+ * k5_plugin_load or k5_plugin_load_all.
+ *
+ * A pluggable interface should have one or more currently supported major
+ * versions, starting at 1. Each major version should have a current minor
+ * version, also starting at 1. If new methods are added to a vtable, the
+ * minor version should be incremented and the vtable stucture should document
+ * where each minor vtable version ends. If method signatures for a vtable are
+ * changed, the major version should be incremented.
+ *
+ * Plugin module implementations (either built-in or dynamically loaded) should
+ * define a function named <interfacename>_<modulename>_initvt, matching the
+ * signature of krb5_plugin_initvt_fn as declared in include/krb5/plugin.h.
+ * The initvt function should check the given maj_ver argument against its own
+ * supported major versions, cast the vtable pointer to the appropriate
+ * interface-specific vtable type, and fill in the vtable methods, stopping as
+ * appropriate for the given min_ver. Memory for the vtable structure is
+ * allocated by the caller, not by the module.
+ *
+ * Dynamic plugin modules are registered with the framework through the
+ * [plugins] section of the profile, as described in the admin documentation
+ * and krb5.conf man page.
+ */
+
+/*
+ * A linked list entry mapping a module name to a module initvt function. The
+ * entry may also include a dynamic object handle so that it can be released
+ * when the context is destroyed.
+ */
+struct plugin_mapping {
+ char *modname;
+ krb5_plugin_initvt_fn module;
+ struct plugin_file_handle *dyn_handle;
+ struct plugin_mapping *next;
+};
+
+/* Holds krb5_context information about each pluggable interface. */
+struct plugin_interface {
+ struct plugin_mapping *modules;
+ krb5_boolean configured;
+};
+
+/* A list of plugin interface IDs. Make sure to increment
+ * PLUGIN_NUM_INTERFACES when a new interface is added, and add an entry to the
+ * interface_names table in lib/krb5/krb/plugin.c. */
+#define PLUGIN_INTERFACE_PWQUAL 0
+#define PLUGIN_INTERFACE_KADM5_HOOK 1
+#define PLUGIN_INTERFACE_CLPREAUTH 2
+#define PLUGIN_INTERFACE_KDCPREAUTH 3
+#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. */
+krb5_error_code
+k5_plugin_load(krb5_context context, int interface_id, const char *modname,
+ krb5_plugin_initvt_fn *module);
+
+/* Retrieve all plugin modules of type interface_id, storing the result
+ * into modules. Free the result with k5_plugin_free_handles. */
+krb5_error_code
+k5_plugin_load_all(krb5_context context, int interface_id,
+ krb5_plugin_initvt_fn **modules);
+
+/* Release a module list allocated by k5_plugin_load_all. */
+void
+k5_plugin_free_modules(krb5_context context, krb5_plugin_initvt_fn *modules);
+
+/* Register a plugin module of type interface_id and name modname. */
+krb5_error_code
+k5_plugin_register(krb5_context context, int interface_id, const char *modname,
+ krb5_plugin_initvt_fn module);
+
+/*
+ * Register a plugin module which is part of the krb5 tree but is built as a
+ * dynamic plugin. Look for the module in modsubdir relative to the
+ * context->base_plugin_dir.
+ */
+krb5_error_code
+k5_plugin_register_dyn(krb5_context context, int interface_id,
+ const char *modname, const char *modsubdir);
+
+/* Destroy the module state within context; used by krb5_free_context. */
+void
+k5_plugin_free_context(krb5_context context);
+