From 7cc4b7a9e624f5eecfbb38607d4cc0870a895671 Mon Sep 17 00:00:00 2001
From: Luke Howard <lukeh@padl.com>
Date: Wed, 5 Jan 2022 13:08:11 +1100
Subject: [PATCH] kdc: KDC plugin API contract notes

Add some notes about the KDC plugin API contract, and require plugins to
explicitly indicate which version of the API they support (remove the macro
alias for the current version).
---
 kdc/kdc-plugin.c               |  2 +-
 kdc/kdc-plugin.h               | 12 ++++++++++--
 tests/plugin/kdc_test_plugin.c |  2 +-
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/kdc/kdc-plugin.c b/kdc/kdc-plugin.c
index 8c07e4083..c8581f41d 100644
--- a/kdc/kdc-plugin.c
+++ b/kdc/kdc-plugin.c
@@ -49,7 +49,7 @@ static const char *kdc_plugin_deps[] = {
 static struct heim_plugin_data kdc_plugin_data = {
     "krb5",
     "kdc",
-    KRB5_KDC_PLUGIN_MINOR,
+    KRB5_PLUGIN_KDC_VERSION_8,
     kdc_plugin_deps,
     kdc_get_instance
 };
diff --git a/kdc/kdc-plugin.h b/kdc/kdc-plugin.h
index b6b08898f..daeb790db 100644
--- a/kdc/kdc-plugin.h
+++ b/kdc/kdc-plugin.h
@@ -86,6 +86,11 @@ typedef krb5_error_code
  *
  * If the function returns KRB5_PLUGIN_NO_HANDLE, the TGS will continue
  * with its default referral handling.
+ *
+ * Note well: the current API contract requires the plugin to NOT free
+ * priv->server_princ if replacing; the KDC will do this. This may change
+ * in a future release, be sure to consult this file whenever the plugin
+ * version changes.
  */
 
 typedef krb5_error_code
@@ -109,8 +114,11 @@ typedef krb5_error_code
 typedef krb5_error_code
 (KRB5_CALLCONV *krb5plugin_kdc_audit)(void *, astgs_request_t);
 
-#define KRB5_KDC_PLUGIN_MINOR		8
-#define KRB5_KDC_PLUGING_MINOR		KRB5_KDC_PLUGIN_MINOR
+/*
+ * Plugins should carefully check API contract notes for changes
+ * between plugin API versions.
+ */
+#define KRB5_PLUGIN_KDC_VERSION_8	8
 
 typedef struct krb5plugin_kdc_ftable {
     int			minor_version;
diff --git a/tests/plugin/kdc_test_plugin.c b/tests/plugin/kdc_test_plugin.c
index 8b4c2cf88..50a9ab80e 100644
--- a/tests/plugin/kdc_test_plugin.c
+++ b/tests/plugin/kdc_test_plugin.c
@@ -152,7 +152,7 @@ audit(void *ctx, astgs_request_t r)
 }
 
 static krb5plugin_kdc_ftable kdc_plugin = {
-    KRB5_KDC_PLUGING_MINOR,
+    KRB5_PLUGIN_KDC_VERSION_8,
     init,
     fini,
     pac_generate,