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

From: Ken Raeburn <[email-masked]>
Date: Tue, 7 Nov 2006 18:56:22 -0800

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
[email-masked]
https://www1.ietf.org/mailman/listinfo/kitten

---

From: Seema Malkani <[email-masked]>
Date: Thu, 09 Nov 2006 13:58:58 -0800

Thanks for the review, Ken.

> the changes from RFC 2853 would've been helpful.

The Abstract has a summary of changes, listing the specific section 
updates. Would a list of changes in an Appendix section at the end of 
the draft be helpful ?

> * changes to various number assignments, new status codes added

The GSS status code update is the one of the significant update to RFC 
2853. The GSS error code values use for GSS exceptions were incorrect in 
the original RFC 2853.

> buried toward the back of the document

RFC 2853 defined the GSS error codes in section 4.12.1. The Static 
constants defined in Java class are listed in section 6.8.1

RFC 2853 update now defines the GSS error codes in section 5.12.1, and 
static constants in section 7.8.1

> * reordered entries in some tables

GSS error code values have been updated, that resulted in the 
re-ordering to be sequential.

> that's on page 31); where are Figures 1 and 2?  Can the labels just  

RFC 2853 was written in text format, hence labeling was easier to add. 
And now RFC 2853 Update has been written in XML format, the labeling 
comes from the standard xml tags.

> places (isn't one enough?), where they weren't specified at all in  

RFC 2853 defined the Credential usage Static constants in section 6.3.2, 
but missed defining the usage values.

This draft defines the Credential usage values in section 7.3.2

> (5.12.1, 7.8.1); I didn't check for consistency

GSS status code values in RFC 2853 were not consistent. The draft now 
defines in GSS error code values that are consistent.

> version has a typo ("Unites States", which is also present in RFC 2744)

This needs to be fixed, I'll make the update.

{ iso(1) member-body(2) United States(840) mit(113554) infosys(1) 
gssapi(2) generic(1) service_name(4) }

> to "value of constant is..."

This update defines the recommended value.

> accept-only for another means you get INITIATE_AND_ACCEPT back?

This needs to be fixed, it should be:

Returns the credential usage flag.  The return value will be one of
GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or
GSSCredential.INITIATE_AND_ACCEPT.

I'll make the update.

> * added required IANA Considerations section, even though there are  

This was required, as mentioned by IETF chair Jeffrey Altman.

> rules, but I would hope we can omit it in that case

The keywords defined in the Normative References are used in the draft. 
Can you clarify what keyword are you referring to ?

> use consistent style for specifying OID values.  Is it "iso(1)" or "1 

RFC 4120, RFC 2744, RFC2743 all define iso(1). This draft follows the 
same. Is this not the correct style ?

> good as the old one, with a few minor issues noted above.
Seema

---

From: Jeffrey Altman <[email-masked]>
Date: Tue, 14 Nov 2006 11:09:15 -0500

Speaking as an individual, not as Chair.

> updates. Would a list of changes in an Appendix section at the end of

The Abstract is just that "an abstract".  It summarizes the contents
of the document so that readers do not have to examine all 100+ pages
to determine if the document is meaningful to them.

In this particular case, since this document replaces the previous
one and does not update it, I think the abstract needs to be corrected.
This document obsoletes RFC2853.  I agree with Ken that the list of
changes should be specified in an Appendix.  The list of changes should
be sufficiently complete so that someone who implemented RFC2853 can
determine whether or not their implementation is still compliant.

> 2853. The GSS error code values use for GSS exceptions were incorrect in

In the Appendix of changes should be a table that indicates what the
wrong values were and what the correct values are.

> comes from the standard xml tags.

You might want to check on the XML2RFC list to see if there is a better
way of handling table labels.

> This draft defines the Credential usage values in section 7.3.2

This should be explicitly stated in the Appendix.

> This update defines the recommended value.

Is this value a SHOULD or a MUST?

Is this a change from RFC2853?

> Can you clarify what keyword are you referring to ?

I suspect Ken is referring to:

MUST, SHOULD, SHOULD NOT, MUST NOT, ....

> same. Is this not the correct style ?

Ken's point is that you should be consistent within this document.  A
quick scan shows both styles:

 { iso(1) member-body(2) United States(840) mit(113554)
   infosys(1) gssapi(2) generic(1) machine_uid_name(2) }

 { 1(iso), 3(org), 6(dod), 1(internet), 5(security),
   6(nametypes), 3(gss-anonymous-name)

I prefer the first.  I agree with Ken, please make them consistent.

Jeffrey Altman

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Mon, 20 Nov 2006 18:09:52 -0500

On Tuesday, November 07, 2006 06:56:22 PM -0800 Ken Raeburn 
<[email-masked]> wrote:

> 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...
>
>     clarifications and corrections to it in response to  identification of
>     transcription errors and implementation experience.

A well-written abstract would stop right there.  This...

> The note-worthy
>     which are replaced by the sections 5.12.1, 7.2.2, 7.3.2, and  7.8.1 of

... belongs in the introduction, but not in the abstract.

> * 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

There is no need for an RFC2119 reference unless requirements keywords from 
that document are actually used.

-- Jeff