svn rev #24422: trunk/ doc/ src/config-files/ src/include/krb5/

[hartmans@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=24422
Commit By: hartmans
Log Message:
Document kadm5_hook interface

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


Changed Files:
U   trunk/doc/admin.texinfo
U   trunk/src/config-files/krb5.conf.M
U   trunk/src/include/krb5/kadm5_hook_plugin.h
Modified: trunk/doc/admin.texinfo
===================================================================
--- trunk/doc/admin.texinfo	2010-10-05 03:29:35 UTC (rev 24421)
+++ trunk/doc/admin.texinfo	2010-10-05 13:57:23 UTC (rev 24422)
@@ -1105,9 +1105,11 @@
 @end table
 
 @node plugins, pkinit client options, dbmodules, krb5.conf
+ at 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 @@
 The following subsections are currently supported within the [plugins]
 section:
 
- at node pwqual interface, , plugins, plugins
+ at node pwqual interface, kadm5_hook interface, plugins, plugins
+ at 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 @@
 Checks against components of the principal name
 @end table
 
+ at node kadm5_hook interface,  , pwqual interface, plugins
+ at 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
 

Modified: trunk/src/config-files/krb5.conf.M
===================================================================
--- trunk/src/config-files/krb5.conf.M	2010-10-05 03:29:35 UTC (rev 24421)
+++ trunk/src/config-files/krb5.conf.M	2010-10-05 13:57:23 UTC (rev 24422)
@@ -752,6 +752,14 @@
 .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

Modified: trunk/src/include/krb5/kadm5_hook_plugin.h
===================================================================
--- trunk/src/include/krb5/kadm5_hook_plugin.h	2010-10-05 03:29:35 UTC (rev 24421)
+++ trunk/src/include/krb5/kadm5_hook_plugin.h	2010-10-05 13:57:23 UTC (rev 24422)
@@ -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>