Subject: Cbind: clearing ptrs/handles on release

From: Martin Rex <[email-masked]>
Date: Wed, 5 Nov 1997 23:10:23 +0100 (MEZ)

I've been reading the current C-Bindings document again ... :-)

I'm proposing the following additions/changes

   7.26.  gss_release_buffer

   buffer            buffer, modify
                     The storage associated with the buffer will be
                     deleted.  The gss_buffer_desc object will not
<                    be freed, but its length field will be zeroed.
>		     be freed, but will be set to GSS_C_EMTPY_BUFFER.

   7.27.  gss_release_cred

   cred_handle       gss_cred_id_t, modify, optional
                     Opaque handle identifying credential
<                    to be released.  If GSS_C_NO_CREDENTIAL
<                    is supplied, the routine will complete
>                    to be released.  The handle will be set
>		     to GSS_C_NO_CREDENTIAL on success.
>		     If GSS_C_NO_CREDENTIAL is supplied as an
>                    input value, the routine will complete
                     successfully, but will do nothing.

   7.28.  gss_release_name

   name              gss_name_t, modify
<                    The name to be deleted.  
>                    The name to be deleted.  The handle will
>                    be set to GSS_C_NO_NAME on success.

   7.29.  gss_release_oid_set

   set               Set of Object IDs, modify
                     The storage associated with the gss_OID_set
<                    will be deleted.
>                    will be deleted.  The pointer will be set
>                    to GSS_C_NO_OID_SET on success.

Supposedly this was the intention why the release calls are passed
the handles by reference, I assume.

By coincidence all those handles are pointers by nature, and once
they're released, any further reference to the memory by the application
would be (semantically) invalid and may easily cause all kinds of
undefined behaviour.

-Martin

---

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Mon, 10 Nov 1997 11:23:13 -0500

From: Martin Rex <[email-masked]>
   Date: Wed, 5 Nov 1997 23:10:23 +0100 (MEZ)

   I'm proposing the following additions/changes...

Certainly the intention of making the release calls take handles was to
_allow_ implementations to clear the pointers if they so desire.

You're proposing to make this behaviour manditory.  It may very well be
a good thing to do, but applications which might link against GSSAPI V1
library probably shouldn't make any assumptions about this behaviour,
since it wasn't required before.  (And we should insert a note warning
application programmers about this fact.)

							- Ted

---

From: Martin Rex <[email-masked]>
Date: Mon, 10 Nov 1997 19:35:42 +0100 (MEZ)

> application programmers about this fact.)

I would say that it was mandatory in V1 already, but it really wasn't
obvious.  ;-)

  the parameters that I am refering in all the release calls are described
  as "modify" in RFC1509, which means that they're input AND output.

RFC1509 (GSS-API v1 C-Bindings):

   2.1.9.2  Mechanism specific status codes
   ...

   The minor_status parameter will always be set by a GSSAPI routine,
   even if it returns a calling error or one of the generic API errors
   indicated above as fatal, although other output parameters may remain
** unset in such cases.  However, output parameters that are expected to
** return pointers to storage allocated by a routine must always set set
** by the routine, even in the event of an error, although in such cases
** the GSSAPI routine may elect to set the returned parameter value to
** NULL to indicate that no storage was actually allocated.  Any length
   field associated with such pointers (as in a gss_buffer_desc
   structure) should also be set to zero in such cases.

To me, this means that in case of success the gssapi mechanism must
set the output parameter to NULL if the value does not (no longer)
refer to storage allocated by the gssapi mechanism.

If the referenced object handle is recognized as invalid, the gssapi
mechanism shouldn't touch it; if it is recognized as a valid handle
to the right object, the release should be performed as completely
as possible and the handle should be cleared upon return
("recognizing" is a local matter, of course.  For robustness, sanity checks
 are recommended for gss_name_t, gss_cred_id_t and gss_ctx_id_t objects).

-Martin

---

From: "Theodore Y. Ts'o" <[email-masked]>
Date: Mon, 10 Nov 1997 14:03:32 -0500

From: Martin Rex <[email-masked]>
   Date: Mon, 10 Nov 1997 19:35:42 +0100 (MEZ)

The way I read that section is that it only applies to those functions
that allocate memory, and not necessarily to those which deallocate
memory:

	``the GSSAPI routine may elect to set the returned parameter
	value to ** NULL to indicate that no storage was actually
	allocated''

It's certainly true that the application shouldn't try to dereference an
object handle after calling free.  However, I think defensive
programming would require that the application not count on the
mechanism actually setting the object handle to NULL or its equivalent;
it's much safer if the application also manually sets the object pointer
to NULL, just in case the mechanism implementor didn't read RFC-1509 the
same way you did.

						- Ted

---

From: Martin Rex <[email-masked]>
Date: Mon, 10 Nov 1997 20:31:40 +0100 (MEZ)

>From the C-Bindings, the object handles are REQUIRED output parameters.
If the routine returns GSS_S_COMPLETE, the output parameter must be
valid!  The only valid output value, if release acutally worked, would
be NULL -- since it means that it doesn't refer to allocated memory.

-Martin