Add documentation to k5-int.h aimed at developers of new pluggable

interfaces.  Add documentation to pwqual_plugin.h aimed at developers
of password quality modules.

git-svn-id: svn://anonsvn.mit.edu/krb5/branches/plugins2@24262 dc483132-0cff-0310-8789-dd5450dbe970

2 files changed, 83 insertions, 1 deletions

diff --git a/src/include/k5-int.h b/src/include/k5-int.h
index f110179..4b2fdd2 100644
--- a/src/include/k5-int.h
+++ b/src/include/k5-int.h
@@ -1431,7 +1431,70 @@ krb5_authdata_free_internal(krb5_context kcontext,
                             krb5_authdata_context context, const char *module,
                             void *ptr);
 
-/* Plugin framework */
+/*** 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
diff --git a/src/include/krb5/pwqual_plugin.h b/src/include/krb5/pwqual_plugin.h
index 48942bc..120ed5f 100644
--- a/src/include/krb5/pwqual_plugin.h
+++ b/src/include/krb5/pwqual_plugin.h
@@ -26,6 +26,24 @@
  *
  *
  * Declarations for password quality plugin module implementors.
+ *
+ * The password quality 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
+ * pwqual_<modulename>_initvt.  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_pwqual_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_PWQUAL_PLUGIN_H
@@ -66,6 +84,7 @@ typedef struct krb5_pwqual_vtable_st {
     krb5_pwqual_open_fn open;
     krb5_pwqual_check_fn check;
     krb5_pwqual_close_fn close;
+    /* Minor version 1 ends here. */
 } *krb5_pwqual_vtable;
 
 #endif /* KRB5_PWQUAL_PLUGIN_H */