Document kadm5_hook interface

* krb5.conf
* admin.texinfo
* kadm5_hook_plugin.h: document initvt requirement

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

1 files changed, 20 insertions, 0 deletions

diff --git a/src/include/krb5/kadm5_hook_plugin.h b/src/include/krb5/kadm5_hook_plugin.h
index 9e8122283..fda72464b 100644
--- a/src/include/krb5/kadm5_hook_plugin.h
+++ b/src/include/krb5/kadm5_hook_plugin.h
@@ -48,6 +48,26 @@
  *
  * This interface depends on kadm5/admin.h. As such, the interface
  * does not provide strong guarantees of ABI stability.
+ *
+ * kadm5_hook plugins should:
+ * kadm5_hook_<modulename>_initvt, matching the signature:
+ *
+ *   krb5_error_code
+ *   kadm5_hook_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 kadm5_hook_vftable_1
+ *
+ * - 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.
  */
 
 #include <krb5/krb5.h>