Subject: Re: [mile] Apps Area review of draft-ietf-mile-enum-reference-format-05

From: Alexey Melnikov <[email-masked]>
Date: Wed, 2 Jul 2014 22:40:38 +0100

Dear Authors,
can you please reply to the AppsDir review?

Thank you,
Alexey

> On 25 Jun 2014, at 18:25, Tim Bray <[email-masked]> wrote:
> 
> I have been selected as the Applications Area Directorate reviewer for
> this draft (for background on appsdir, please
> seehttp://trac.tools.ietf.org/area/app/trac/wiki/ApplicationsAreaDirectorate
> ).
> 
> Please resolve these comments along with any other Last Call comments
> you may receive. Please wait for direction from your document shepherd
> or AD before posting a new version of the draft.
> 
> Document:draft-ietf-mile-enum-reference-format-05
> Title: IODEF Enumeration Reference Format
> Reviewer:Tim Bray
> Review Date: June 25, 2014
> 
> There are problems in this document which should be addressed before
> publication.
> 
> 1. The description uses many technical terms without first either
> defining them or giving a reference for their meaning:  “Reference
> class”, “Enumeration values”, "enumeration identifiers and their
> references”.  This reviewer found the spec really hard to understand
> due to the heavy use of specialized language with no definition of
> terms.  NOTE: It may be reasonable to decide that this specification
> is only intended to be read by those who are already sufficiently
> expert to understand the terms, in which case this wouldn’t be a
> problem.
> 
> 2. Why introduce two child elements, rather than just add an
> attribute?  Here’s the example:
> 
> <ReferenceName>
>   <Index>1</Index>
>   <ID>CXI-1234-XYZ</ID>
> </ReferenceName>
> 
> An attribute would feel more idiomatic. Why not
> 
> <ReferenceName Index="1">CXI-1234-XYZ</ReferenceName> ?
> 
> Suggested improvements to the spec:
> 
> Abstract: This at least should be comprehensible to nonspecialists.
> Here is a suggested rewrite:
> 
> The The Incident Object Description Exchange Format (IODEF) is an XML
> construct which contains identifiers, using an element called
> ReferenceName, that come from enumerations of fixed string values.  At
> the moment the content of ReferenceName is just a string field, which
> is unsatisfactory because it is necessary to know both the value and
> the enumeration from which it comes. This specification changes the
> definition of ReferenceName by adding structure which identifies both
> the value and the enumeration from which it comes.  This is done
> indirectly through an IANA registry.
> 
> In the first paragraph of section 2, the word “resulting” is wrong.  I
> think the sentence is trying to say “to require that the ReferenceName
> element identify both the enumeration from which the name comes and
> the name itself, and to identify enumerations via an IANA registry,
> which includes useful metadata such as a link to the enumeration’s
> specification.”
> 
> FIGURE 1 identifies the structure of Reference *before* this draft.
> Why not provide before-and-after pictures?
> 
> Section 2, para beginning “Per IODEF”, language is clumsy “specific
> references, such as ... are referenced.”  Perhaps something like
> “becomes problematic when the ReferenceName comes from a particular
> enumeration such as CVE [CVE], CCE [CCE], or CPE [CPE] and it is not
> obvious to an implementer how to determine which. One solution,
> presented here, is to add structure to the ReferenceName to identify
> both the value and the enumeration it comes from“.
> 
> Section 2.1, should the title become something like “Revised
> ReferenceName Format”?
> 
> Also, sort of roundabout. How about “... and requires a child elements
> named "Index" and "ID"; the first contains an integer which identifies
> an entry in an IANA registry (see Section 4), which specifies the
> specification the actual enumeration value, provided as the content of
> the “ID” child element.  Or, as suggested above, make Index an
> attribute, then you don’t need ID.
> 
> The name “Index” is lousy.  Yes, it’s an integer index into an IANA
> registry, but element names should describe what the content means,
> not its data format. This identifies is a enumeration or a namespace
> or a specification.  Maybe SpecIndex? or Enumeration?
> 
> Also, in the IANA table, shouldn’t the spec say something about what
> kind of thing the Specification URI is supposed to identify?  An I-D?
> An RFC? An XSD?
> 
> -- 
> - Tim Bray (If you’d like to send me a private message, see
> https://keybase.io/timbray)

---

From: "Adam W. Montville" <[email-masked]>
Date: Thu, 3 Jul 2014 11:17:59 -0500

Hi Tim,

Thank you for your review.  Please see my comments inline.

Regards,

Adam

> expert to understand the terms, in which case this wouldn’t be a

We could attempt to define enumeration, however, the overview language in section 2 does provide examples of such enumerations (CVE, CCE, CPE).  Because this enumeration reference format is tied closely to IODEF, I’m not convinced we need to go down the road of defining what we mean when those involved in security automation are probably very familiar with CVE, CCE, CPE, and so on.  I’m especially not convinced given the suggested abstract rewrite, which I like.

> <ReferenceName Index="1">CXI-1234-XYZ</ReferenceName> ?

This is a reasonable suggestion.  I’m fine with either choice.  Does one method have value over the other from an implementation perspective (I’m asking all)?

> indirectly through an IANA registry.

If there are no objections, I quite like this modification to the abstract.

> which includes useful metadata such as a link to the enumeration’s

Would it be enough to change from “…resulting reference formats” to “…resulting values in the specified format.” ?  The final sentence would read: “There are several ways to accomplish this goal, but the most appropriate at this point is to require a specific format for the ReferenceName string of the IODEF [IODEF] Reference class, and use an IANA registry to manage the resulting values in the specified format.”  This change was recommended by our responsible AD.

> Why not provide before-and-after pictures?

Is an “after” picture really necessary given the XML listings and language descriptions?  I’m not convinced it would be.  Additionally, if an “after” picture were created, it would probably turn out to be a picture of ReferenceName rather than the overall picture, which may then be viewed as disjointed from the “before” picture anyway.

> both the value and the enumeration it comes from“.

I have no issues making this change.

> Section 2.1, should the title become something like “Revised

I have no issues making this change.

> attribute, then you don’t need ID.

I’m not entirely sure I followed this one, but let’s see if using an attribute will fly and then address this one.

> or a specification.  Maybe SpecIndex? or Enumeration?

Agreed.  SpecIndex or Enumeration would work for me, but I think SpecIndex is better because it’s a bit more generic than Enumeration.  Are there other suggestions here?

> kind of thing the Specification URI is supposed to identify?  An I-D?

The Specification URI is a list of one or more URIs.  Then, we’d need a descriptor for each potential URI associated with the Index.  Is that what you had in mind, or something else?

---

From: "Waltermire, David A." <[email-masked]>
Date: Thu, 3 Jul 2014 16:45:42 +0000

Adam,

In my view, we should make this specification as approachable as possible to non-domain experts. I am not sure we can assume that all readers are familiar with CVE, CCE, and CPE. The comment about enumerations resonates with me. This may get addressed by the abstract changes, which may make this moot, but it may make sense to use less specialized language. For example we could use collection/set of identifiers (or "identification set") instead of enumeration.

Thoughts?

Dave

-----Original Message-----
From: Adam W. Montville [mailto:[email-masked]] 
Sent: Thursday, July 03, 2014 12:18 PM
To: Tim Bray
Cc: [email-masked]; [email-masked]; [email-masked]; The IESG
Subject: Re: Apps Area review of draft-ietf-mile-enum-reference-format-05

Hi Tim,

Regards,

Adam

On Jun 25, 2014, at 12:25 PM, Tim Bray <[email-masked]> wrote:

> Title: IODEF Enumeration Reference Format Reviewer:Tim Bray Review 
> Date: June 25, 2014
> 
> defining them or giving a reference for their meaning:  "Reference 
> class", "Enumeration values", "enumeration identifiers and their 
> references".  This reviewer found the spec really hard to understand 
> expert to understand the terms, in which case this wouldn't be a 
> problem.

We could attempt to define enumeration, however, the overview language in section 2 does provide examples of such enumerations (CVE, CCE, CPE).  Because this enumeration reference format is tied closely to IODEF, I'm not convinced we need to go down the road of defining what we mean when those involved in security automation are probably very familiar with CVE, CCE, CPE, and so on.  I'm especially not convinced given the suggested abstract rewrite, which I like.

> attribute?  Here's the example:
> 
> <ReferenceName>
>   <Index>1</Index>
>   <ID>CXI-1234-XYZ</ID>
> </ReferenceName>
> 

This is a reasonable suggestion.  I'm fine with either choice.  Does one method have value over the other from an implementation perspective (I'm asking all)?

> 
> In the first paragraph of section 2, the word "resulting" is wrong.  I 
> think the sentence is trying to say "to require that the ReferenceName 
> which includes useful metadata such as a link to the enumeration's 
> specification."

Would it be enough to change from "...resulting reference formats" to "...resulting values in the specified format." ?  The final sentence would read: "There are several ways to accomplish this goal, but the most appropriate at this point is to require a specific format for the ReferenceName string of the IODEF [IODEF] Reference class, and use an IANA registry to manage the resulting values in the specified format."  This change was recommended by our responsible AD.

> Why not provide before-and-after pictures?

Is an "after" picture really necessary given the XML listings and language descriptions?  I'm not convinced it would be.  Additionally, if an "after" picture were created, it would probably turn out to be a picture of ReferenceName rather than the overall picture, which may then be viewed as disjointed from the "before" picture anyway.

> 
> Section 2, para beginning "Per IODEF", language is clumsy "specific 
> references, such as ... are referenced."  Perhaps something like 
> "becomes problematic when the ReferenceName comes from a particular 
> both the value and the enumeration it comes from".

> 
> Section 2.1, should the title become something like "Revised 
> ReferenceName Format"?

> 
> Also, sort of roundabout. How about "... and requires a child elements 
> the "ID" child element.  Or, as suggested above, make Index an 
> attribute, then you don't need ID.

I'm not entirely sure I followed this one, but let's see if using an attribute will fly and then address this one.

> 
> The name "Index" is lousy.  Yes, it's an integer index into an IANA 

Agreed.  SpecIndex or Enumeration would work for me, but I think SpecIndex is better because it's a bit more generic than Enumeration.  Are there other suggestions here?

> 
> Also, in the IANA table, shouldn't the spec say something about what 

The Specification URI is a list of one or more URIs.  Then, we'd need a descriptor for each potential URI associated with the Index.  Is that what you had in mind, or something else?

> 
> --
> - Tim Bray (If you'd like to send me a private message, see

---

From: Tim Bray <[email-masked]>
Date: Thu, 3 Jul 2014 10:20:22 -0700

On Thu, Jul 3, 2014 at 9:17 AM, Adam W. Montville <[email-masked]>
wrote:

>
> We could attempt to define enumeration, however, the overview language in
> section 2 does provide examples of such enumerations (CVE, CCE, CPE).
>  Because this enumeration reference format is tied closely to IODEF, I’m
> not convinced we need to go down the road of defining what we mean when
> those involved in security automation are probably very familiar with CVE,
> CCE, CPE, and so on.  I’m especially not convinced given the suggested
> abstract rewrite, which I like.
>

​Sounds like you’re on your way to a solution.​

> This is a reasonable suggestion.  I’m fine with either choice.  Does one
> method have value over the other from an implementation perspective (I’m
> asking all)?
>

​The only real unambiguous advantage is that you have two markup constructs
instead of three.  Also, I guess, a few less bytes.  There’s an intangible
argument in that this is the sort of thing attributes are supposed to be
for; here’s a data value and here’s some metadata about it, e.g. its
namespace.​

> Is an “after” picture really necessary given the XML listings and language
> descriptions?  I’m not convinced it would be.  Additionally, if an “after”
> picture were created, it would probably turn out to be a picture of
> ReferenceName rather than the overall picture, which may then be viewed as
> disjointed from the “before” picture anyway.
>

​Or, maybe just take out the ASCII art. It’s not obvious it adds much
value.  Or if you leave it in, attach a label to make it clear that it
describes the *current* structure before the change described by the draft
is made.​

> Agreed.  SpecIndex or Enumeration would work for me, but I think SpecIndex
> is better because it’s a bit more generic than Enumeration.  Are there
> other suggestions here?
>
> The Specification URI is a list of one or more URIs.  Then, we’d need a
> descriptor for each potential URI associated with the Index.  Is that what
> you had in mind, or something else?
>

​Hm, no, I mean, are there any constraints on who’s allowed to specify
enumerations, what kinds of things should implementers be prepared to deal
with?  Can any storefront publish a one-page description of some values and
expect implementers to find use in it?  I have no ideas or opinions about
the answers to this question, but I think it’s a real question.  When I see
a “URL of the specification” with no remarks about what kind of beast it
might be or where it comes from, that makes me nervous (and it might make
the IESG nervous too).​

---

From: "Adam W. Montville" <[email-masked]>
Date: Mon, 7 Jul 2014 07:57:31 -0500

On Jul 3, 2014, at 12:20 PM, Tim Bray <[email-masked]> wrote:

> ​Hm, no, I mean, are there any constraints on who’s allowed to specify enumerations, what kinds of things should implementers be prepared to deal with?  Can any storefront publish a one-page description of some values and expect implementers to find use in it?  I have no ideas or opinions about the answers to this question, but I think it’s a real question.  When I see a “URL of the specification” with no remarks about what kind of beast it might be or where it comes from, that makes me nervous (and it might make the IESG nervous too).​

Ah, I see.  We do have a requirement for expert review of entries, which should reduce the likelihood of odd publications to the IANA table.  Any entry being made to the IANA table, in being subject to expert review, would have the specification URL vetted to ensure that the URL is suitable for implementers to reference.

---

From: Tim Bray <[email-masked]>
Date: Mon, 7 Jul 2014 10:43:13 -0700

Ah, right, the expert review is better than nothing.  Might it be useful to
provide guidance for expert reviewers in this RFC as to what implementers
need to find in an enumeration spec?  Just giving a URL-for-a-spec does
leave the feeling of a missing piece.

On Mon, Jul 7, 2014 at 5:57 AM, Adam W. Montville <[email-masked]>
wrote:

> Ah, I see.  We do have a requirement for expert review of entries, which
> should reduce the likelihood of odd publications to the IANA table.  Any
> entry being made to the IANA table, in being subject to expert review,
> would have the specification URL vetted to ensure that the URL is suitable
> for implementers to reference.
>