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 0918d1511cbf58d2377cf3501a8009130e89bcd9..3fc065c2514c5f2af6f9cfb580de3b39064afc44 100644 (file)
--- 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.
 
 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
 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