krb5 commit: Use standard comment in certauth plugin header

[Greg Hudson]

https://github.com/krb5/krb5/commit/a96ac7f73b5804a9c34033539a933ec0b64cce11
commit a96ac7f73b5804a9c34033539a933ec0b64cce11
Author: Greg Hudson <ghudson at mit.edu>
Date:   Sat Aug 19 14:26:15 2017 -0400

    Use standard comment in certauth plugin header
    
    Each pluggable interface header needs to include some boilerplate text
    to make it clear what a module implementor needs to provide.  Include
    that text in certauth_plugin.h.
    
    ticket: 8561

 src/include/krb5/certauth_plugin.h |   29 ++++++++++++++++++++++++++---
 1 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/src/include/krb5/certauth_plugin.h b/src/include/krb5/certauth_plugin.h
index 0b3a58b..3074790 100644
--- a/src/include/krb5/certauth_plugin.h
+++ b/src/include/krb5/certauth_plugin.h
@@ -31,10 +31,33 @@
  */
 
 /*
- * Certificate authorization plugin interface.  The PKINIT server module uses
- * this interface to check client certificate attributes after the certificate
- * signature has been verified.
+ * Declarations for certauth plugin module implementors.
+ *
+ * The certauth pluggable interface currently has only one supported major
+ * version, which is 1.  Major version 1 has a current minor version number of
+ * 1.
+ *
+ * certauth plugin modules should define a function named
+ * certauth_<modulename>_initvt, matching the signature:
+ *
+ *   krb5_error_code
+ *   certauth_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 krb5_certauth_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_CERTAUTH_PLUGIN_H
 #define KRB5_CERTAUTH_PLUGIN_H