comments on java bindings update, draft-ietf-kitten-rfc2853bis-02

[Ken Raeburn <[e-mail]>]

Jeff was complaining because not enough people had reviewed the java  
bindings, so I took a look.  Not that I'm any great expert on Java,  
but I do okay with English and sometimes even with GSSAPI...

The abstract says in part:

      This document
    updates the Java bindings for the GSS-API that are specified in
    "Generic Security Service API version 2 : Java Bindings" (RFC2853).
    This document obsoletes RFC2853 by making specific and incremental
    clarifications and corrections to it in response to  
identification of
    transcription errors and implementation experience.  The note-worthy
    changes are in sections 4.12.1, 6.2.2, 6.3.2, and 6.8.1 of RFC2853,
    which are replaced by the sections 5.12.1, 7.2.2, 7.3.2, and  
7.8.1 of
    this document, where numerical constants were either added or
    modified.

But aside from this, I didn't see a detailed description of just  
what's changed from the previous version.  (I didn't go back and  
check the email archives though.)  A non-normative section listing  
the changes from RFC 2853 would've been helpful.

So I poked at the two versions with Emacs a bit, stripping out page  
headers and footers and line breaks and comparing what was left.  I  
think my list covers everything changed, and I've got comments on  
some of the changes:

* minor grammatical fixes, basic text changes in the intro relating  
to this being an update

* changes to various number assignments, new status codes added

* description of some error codes as returned only during context  
establishment is duplicated in initial list of status codes, not just  
buried toward the back of the document

* reordered entries in some tables

* added labels "Figure 3" through "Figure 9" to various tables,  
though the labels aren't always on the same page as the table being  
labeled (e.g., "Figure 3" at the top of page 32, describing the table  
that's on page 31); where are Figures 1 and 2?  Can the labels just  
go away?

* java syntax tweaks (array parameters, missing return types)

* specify values for INITIATE_AND_ACCEPT and friends in a bunch of  
places (isn't one enough?), where they weren't specified at all in  
rfc2853

* status code values being specified in a couple of places now  
(5.12.1, 7.8.1); I didn't check for consistency

* change NT_HOSTBASED_SERVICE OID value from the deprecated value to  
the current one (as described in the C bindings in RFC 2744); the new  
version has a typo ("Unites States", which is also present in RFC 2744)

* change text describing lifetime constants from "must be set to..."  
to "value of constant is..."

* clarify GSSCredential.getUsage() to say it return the flag "as a  
union over all mechanisms".  I assume this means the union of all  
functionality in each of the mechanisms, so initiate-only for one and  
accept-only for another means you get INITIATE_AND_ACCEPT back?

* added some missing references

* flattened some sections, like:
- old: 6.4.3 initSecContext, 6.4.3.1 example code for 6.4.3, 6.4.4  
initSecContext, 6.4.4.1 example code for 6.4.4, 6.4.5  
acceptSecContext, 6.4.5.1 example code for 6.4.5, ...
- new: 7.4.3 initSecContext, 7.4.4 example code for 7.4.3, 7.4.5  
initSecContext, 7.4.6 example code for 7.4.5, 7.4.7 acceptSecContext,  
7.4.8 example code for 7.4.7

I think I like the old structure better, personally.  Some of the  
bits of example code are small enough that I think you could just  
merge them into the preceding sections.  It's a pretty minor point,  
though.

* removed duplicated parameter names in descriptions in getMIC  
description in (old) 6.4.15

* added required IANA Considerations section, even though there are  
no such considerations

* corrected name of References section

* updated IPR & Copyright, new authors' addresses

* inserted the usual "conventions used in this document" section,  
before the introduction (resulting in a renumbering of sections  
through the whole document), even though the key words described  
there are not actually used in the document; I haven't checked the  
rules, but I would hope we can omit it in that case

RFC 2744 inconsistencies notwithstanding, I think this spec should  
use consistent style for specifying OID values.  Is it "iso(1)" or "1 
(iso)"?

So, I've mentioned above things that were changed and some minor  
issues I spotted looking at the changes.  I haven't actually *read  
through* the new version in all its 105-page glory, so far.  But most  
of the changes seem strictly mechanical (section renumbering) or  
localized, so I think it's safe to say the new version is at least as  
good as the old one, with a few minor issues noted above.

Ken

_______________________________________________
Kitten mailing list
[e-mail]
https://www1.ietf.org/mailman/listinfo/kitten