Re: [kitten] New Version Notification for draft-kaduk-kitten-gss-loop-02.txt (fwd)

[Jeffrey Hutzelman <[e-mail]>]

On Sat, 2014-01-18 at 00:22 -0600, Nico Williams wrote:

> RFC2744, section 5.26 requires nothing.  It doesn't say "MUST", and so
> on (because RFC2744 doesn't reference RFC2119, of course).

No, it pretty clearly says "the routine will zero the length field...".
The text is descriptive in its phrasing, because the whole document is
written more like API documentation for callers than a standard for
implementors.  However, it is in fact the latter, and so a statement
about what a routine _will_ do is pretty clearly prescriptive in intent.

Similarly, it's pretty clear that releasing a buffer with NULL value is
required to be safe, per the last sentence in that same paragraph.  



>   It doesn't
> say that the value field will not be set.

No.  It fairly clearly leaves that up to the implementor.


>   Section 3.9.2 seems to
> indicate that the value field ought to be set, but only if the buffer
> is an output buffer.

Section 3.9.2 requires that the value be set for an output parameter
that is "expected to return pointers to storage allocated by a routine".
That's sane; it means, for example, that after you call a GSS-API
routine that has a buffer output, it is always safe to call
gss_release_buffer on that buffer, whether or not the routine succeeded,
and whether or not it actually allocated any storage.

However, section 3.9.2 has nothing to say about the buffer descriptor
passed to gss_release_buffer, even if we consider that to be an output
buffer.  Why?  Because the purpose of gss_release_buffer is to free
storage, not to allocate it.  More particularly, the buffer parameter to
this routine is not used to return a pointer to allocated storage; it is
used to pass in a pointer to storage to be freed, possibly with the
side-effect that the pointer is set to NULL, but certainly not that it
is set to point to allocated storage!

Perhaps more directly to the point, 3.9.2 is part of a section
describing general calling conventions, while the text in 5.26 pertains
specifically to gss_release_buffer _and_ has something specific to say
about the pointer (namely, that implementations are "encouraged" to set
it to NULL.  This, I thikn, has about the same strength that naive
readers assign to "SHOULD").



> > If it is okay for the sample code to rely on this behavior, in spite of
> > RFC 2744 not specifying that it is okay, then perhaps the comment should
> > be clarified or removed to avoid confusing people like it did Martin.
> 
> I would just note that RFC2744 can be interpreted as permitting
> gss_release_buffer() implementations to set the length field but not
> the value field.  But I'd rather just say that RFC2744 just has a
> glaring omission... because that's what it is.

Except I wouldn't call it an omission, in that it appears quite
deliberate.  Why say that implementations are "encouraged" to set the
pointer to NULL, rather than either making it required or saying nothing
at all?  Perhaps to avoid rendering some existing implementation(s)
noncompliant?



The reality is that people tend to copy and paste example code, often
without really understanding it.  To some extent, that's the point -- we
want people to be able to get this right _without_ investing months or
years becoming expert enough to work out all of the possible cases.  In
light of that, I think such example code needs to be of the highest
quality, which certainly means it should not make unfounded assumptions
about the interface it purports to document.

-- Jeff