kdc: document windc plugin entry points

kdc/windc_plugin.h

@@ -39,20 +39,13 @@
 #include <krb5.h>
 #include <kdc.h>
 
-/*
- * The PAC generate function should allocate a krb5_pac using
- * krb5_pac_init and fill in the PAC structure for the principal using
- * krb5_pac_add_buffer.
- *
- * The PAC verify function should verify the PAC KDC signatures by fetching
- * the right KDC key and calling krb5_pac_verify() with that KDC key.
- * Optionally, update the PAC buffers upon success.
- *
- * Check client access function check if the client is authorized.
- */
-
 struct hdb_entry_ex;
 
+/*
+ * Allocate a PAC for the given client with krb5_pac_init(),
+ * and fill its contents in with krb5_pac_add_buffer().
+ */
+
 typedef krb5_error_code
 (KRB5_CALLCONV *krb5plugin_windc_pac_generate)(void *, krb5_context,
 					       struct hdb_entry_ex *, /* client */
@@ -61,6 +54,12 @@ typedef krb5_error_code
 					       uint64_t,	      /* pac_attributes */
 					       krb5_pac *);
 
+/*
+ * Verify the PAC KDC signatures by fetching the appropriate TGS key
+ * and calling krb5_pac_verify() with that key. Optionally update the
+ * PAC buffers on success.
+ */
+
 typedef krb5_error_code
 (KRB5_CALLCONV *krb5plugin_windc_pac_verify)(void *, krb5_context,
 			       const krb5_principal, /* new ticket client */
@@ -70,9 +69,18 @@ typedef krb5_error_code
 			       struct hdb_entry_ex *,/* krbtgt */
 			       krb5_pac *);
 
+/*
+ * Authorize the client principal's access to the Authentication Service (AS).
+ * This function is called after any pre-authentication has completed.
+ */
+
 typedef krb5_error_code
 (KRB5_CALLCONV *krb5plugin_windc_client_access)(void *, astgs_request_t);
 
+/*
+ * Update the AS or TGS reply immediately prior to encoding.
+ */
+
 typedef krb5_error_code
 (KRB5_CALLCONV *krb5plugin_windc_finalize_reply)(void *, astgs_request_t r);