svn rev #24903: trunk/src/lib/gssapi/krb5/

[ghudson@MIT.EDU]

http://src.mit.edu/fisheye/changelog/krb5/?cs=24903
Commit By: ghudson
Log Message:
The MIT krb5 and Heimdal implementations of
gss_krb5_export_lucid_sec_context error on version arguments other
than 1, so the version negotiation described in the function
documentation would not be backward-compatible.  Change the docs so
that the caller can assume the returned structure is of the requested
version, but the caller will be responsible for retrying with lower
version numbers on error.  (Unfortunately, Heimdal and MIT return
different error codes, and MIT's is in a currently-unpublished header,
so we can't document the error code for unknown versions.)



Changed Files:
U   trunk/src/lib/gssapi/krb5/gssapi_krb5.hin
Modified: trunk/src/lib/gssapi/krb5/gssapi_krb5.hin
===================================================================
--- trunk/src/lib/gssapi/krb5/gssapi_krb5.hin	2011-04-27 17:12:07 UTC (rev 24902)
+++ trunk/src/lib/gssapi/krb5/gssapi_krb5.hin	2011-04-27 22:09:29 UTC (rev 24903)
@@ -147,8 +147,8 @@
 } gss_krb5_lucid_context_v1_t;
 
 /*
- * Mask for determining the returned structure version.
- * See example below for usage.
+ * Mask for determining the version of a lucid context structure.  Callers
+ * should not require this.
  */
 typedef struct gss_krb5_lucid_context_version {
     OM_uint32       version;        /* Structure version number */
@@ -219,17 +219,10 @@
  * The caller must call gss_krb5_free_lucid_context() to free
  * the context and allocated resources when it is finished with it.
  *
- * 'version' is an integer indicating the highest version of lucid
- * context understood by the caller.  The highest version
- * understood by both the caller and the GSS implementation must
- * be returned.  The caller can determine which version of the
- * structure was actually returned by examining the version field
- * of the returned structure.  gss_krb5_lucid_context_version_t
- * may be used as a mask to examine the returned structure version.
+ * 'version' is an integer indicating the requested version of the lucid
+ * context.  If the implementation does not understand the requested version,
+ * it will return an error.
  *
- * If there are no common versions, an error should be returned.
- * (XXX Need error definition(s))
- *
  * For example:
  *      void *return_ctx;
  *      gss_krb5_lucid_context_v1_t *ctx;
@@ -240,17 +233,7 @@
  *      maj_stat = gss_krb5_export_lucid_sec_context(&min_stat,
  *                      ctx_handle, 1, &return_ctx);
  *      // Verify success
- *
- *      vers = ((gss_krb5_lucid_context_version_t *)return_ctx)->version;
- *      switch (vers) {
- *      case 1:
- *              ctx = (gss_krb5_lucid_context_v1_t *) return_ctx;
- *              break;
- *      default:
- *              // Error, unknown version returned
- *              break;
- *      }
- *
+ *      ctx = (gss_krb5_lucid_context_v1_t *) return_ctx;
  */
 
 OM_uint32 KRB5_CALLCONV