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

3 files changed, 40 insertions, 1 deletions

diff --git a/doc/admin.texinfo b/doc/admin.texinfo
index 2a811de96b..9c0d2904e0 100644
--- a/doc/admin.texinfo
+++ b/doc/admin.texinfo
@@ -1105,9 +1105,11 @@ This LDAP specific tags indicates the number of connections to be maintained per
 @end table
 
 @node plugins, pkinit client options, dbmodules, krb5.conf
+@subsection Plugins
 
 @menu
 * pwqual interface::             
+* kadm5_hook interface::
 @end menu
 
 Tags in the [plugins] section can be used to register dynamic plugin
@@ -1140,7 +1142,8 @@ then the named modules will be disabled for the pluggable interface.
 The following subsections are currently supported within the [plugins]
 section:
 
-@node pwqual interface, , plugins, plugins
+@node pwqual interface, kadm5_hook interface, plugins, plugins
+@subsubsection pwqual interface
 
 The pwqual subsection controls modules for the password quality
 interface, which is used to reject weak passwords when passwords are
@@ -1162,6 +1165,14 @@ built with Hesiod support)
 Checks against components of the principal name
 @end table
 
+@node kadm5_hook interface,  , pwqual interface, plugins
+@subsubsection kadm5_hook interface
+The kadm5_hook interface provides plugins with information on
+principal creation, modification, password changes and deletion. This
+interface can be used to write a plugin to synchronize MIT Kerberos
+with another database such as Active Directory. No plugins are built
+in for this interface.
+
 @node pkinit client options, Sample krb5.conf File, plugins, krb5.conf
 @subsection pkinit options
 
diff --git a/src/config-files/krb5.conf.M b/src/config-files/krb5.conf.M
index e658e8997f..d03a1f468b 100644
--- a/src/config-files/krb5.conf.M
+++ b/src/config-files/krb5.conf.M
@@ -752,6 +752,14 @@ built with Hesiod support)
 .IP princ
 Checks against components of the principal name
 
+.SS kadm5_hook interface
+
+The kadm5_hook interface provides plugins with information on
+principal creation, modification, password changes and deletion. This
+interface can be used to write a plugin to synchronize MIT Kerberos
+with another database such as Active Directory. No plugins are built
+in for this interface.
+
 .SH FILES 
 /etc/krb5.conf
 .SH SEE ALSO
diff --git a/src/include/krb5/kadm5_hook_plugin.h b/src/include/krb5/kadm5_hook_plugin.h
index 9e81222836..fda72464b3 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>