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

diff --git a/doc/admin.texinfo b/doc/admin.texinfo
index 2a811de96b46556fcd0b979f33ec5ee6fab7ac68..9c0d2904e04b04d4efe550814d5125f0a5bd096f 100644 (file)
--- 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 e658e8997ffaa814fd65e6f18d3d6a8276afe25e..d03a1f468b7316e7d0a47bcacc205bd052e1fc82 100644 (file)
--- 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 9e81222836d10f74299cc267c3bad56701e14d18..fda72464b3ca0ad744c304685c14cf71152a79d0 100644 (file)
--- 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>