From: Greg Hudson <ghudson@mit.edu>
Date: Sat, 23 May 2026 21:48:35 +0000 (-0400)
Subject: Document gss_internal_release_oid()
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;ds=inline;p=thirdparty%2Fkrb5.git

Document gss_internal_release_oid()

In the GSSAPI mechanism module documentation, recommend implementing
gss_internal_release_oid() and specify its interface.
---

diff --git a/doc/plugindev/gssapi.rst b/doc/plugindev/gssapi.rst
index 0918d1511c..3fc065c251 100644
--- a/doc/plugindev/gssapi.rst
+++ b/doc/plugindev/gssapi.rst
@@ -20,6 +20,20 @@ a module does not wish to implement a GSSAPI extension, it can simply
 refrain from exporting it, and the mechglue will fail gracefully if
 the application calls that function.
 
+GSSAPI mechanism modules should implement a
+**gss_internal_release_oid** function, to help protect against an
+application mistakenly calling **gss_release_oid** on a statically
+allocated OID pointer.  The function should have the following
+signature::
+
+    OM_uint32 gss_internal_release_oid(OM_uint32 *minor_status,
+        gss_OID *oid);
+
+If the function recognizes ``*oid`` as a pointer that could be yielded
+by one of the module's other functions, it should set ``*oid`` to
+**GSS_C_NO_OID** and return **GSS_S_COMPLETE**.  Otherwise it should
+return **GSS_S_CONTINUE_NEEDED**.
+
 The mechglue does not invoke a module's **gss_add_cred**,
 **gss_add_cred_from**, **gss_add_cred_impersonate_name**, or
 **gss_add_cred_with_password** function.  A mechanism only needs to