Subject: [Gen-art] Gen-ART Early Review of draft-hoffman-xml2rfc-04

From: Ben Campbell <[email-masked]>
Date: Thu, 3 Apr 2014 18:05:00 -0500

I am the assigned Gen-ART reviewer for this draft. For background on
Gen-ART, please see the FAQ at

<http://wiki.tools.ietf.org/area/gen/trac/wiki/GenArtfaq>.

Please resolve these comments along with any other comments
you may receive.

Document: draft-hoffman-xml2rfc-04
Reviewer: Ben Campbell
Review Date:  2014-04-03
IETF LC End Date: Not in last call

Note: This is an early review, rather than the usual Gen-ART review at IETF last call. The Gen-ART processes do not precisely apply.

Summary: This draft is on the right track. I have a few comments and questions that may or may not be worth consideration.

*** Major Issues: ***

None

*** Minor issues: ***

-- General:

There are a few "to do" items left in the draft.  (Not surprising for an early review.)

-- Section 1, paragraph 2:

I find it confusing that we have two drafts in parallel, one for V2 that is obsoleted by this draft, and this draft for V3. With this draft copying much of V2 forward, which is authoritative?

-- 1.1, entry for <tident>

THANK YOU!!!! I think faking indented text using the <list> work around was one of the most annoying things about previous versions.

--2.2:

Can I have more than one of any given address sub-element? If so, how should it render?

-- 2.5.3:

If "height" ought to be avoided, should it be deprecated?

Also, what's the unit for height?

(Same questions apply to "width")

-- 2.5.5:

An example of how to use inlined graphics files might be helpful.

-- 2.5.6:

A generic "code" value might be useful. Otherwise, how do you expect these to be used? Syntax highlighting? I assume the processor should never actually try to interpret code based on the "type" attribute. (Are there security considerations there?)

-- 2.7:

It seems like <b> (and also <i>)  is just as much format dependent as things like <width>. Wouldn't something like <em> be more useful for this purpose, where you have an abstract concept of emphasis that can be rendered differently for different formats? This seems like a place where our use cases are different than those for HTML, where markup is usually rendered by browsers that have similar font display capabilities.

In particular, what happens to <b>text<.b> when rendered into ASCII text?

-- 2.9:

Why does the "cite" attribute have different requirements than, say, xref? In particular, why wouldn't I want to cite a reference in the current doc, rather than a URL?

-- 2.9.1:

How would one reference an auto generated anchor identifier? If it doesn't exist until processing time...?

-- 2.15.2

What is the format for Month? Must you write it out? Abbreviate? Number?)

-- 2.26

An example might be helpful

--2.33.2

Is it possible to continue numbering from a previous list?

-- 2.43.5

The text says that "iprExtract" is used to reference a specific section.... Can you elaborate on how? E.g. do you reference an anchor? Are you allowed to have more than one "as-is" section?

-- 2.44.2:

Why are numberless subsections disallowed? It's pretty common to see documents that have non-numbered sub-heads inside numbered sections.

-- 2.44.5:

The default for the TOC attribute is "default"? Does that mean the actual meaning of "default" is controlled elsewhere?

Also, is there a way to limit the depth for ToCs?

-- 2.45 (and subsections)

Should the seriesInfo "name" values match the table from 2.40?

-- 2.54:

Is it possible to select the symbol to be used for an unordered list?

-- 5, security considerations

I wonder if the possibility of executable content existing in an RFC or draft is worth mention here? For an extreme example, see RFC6716, Appendix A. But more realistically, 2.5.5 mentions the possibility of in-lined binary content, and 2.5.6 allows the identification of code in a way that a naive processor implementation might take as an invitation to interpret said code.

Also, does the need for a processor to potentially render binary content in general (in-lined or otherwise) expand the attack surface over that for previous versions of XML2RFC?

*** Nits/editorial comments: ***

-- 1, paragraph 3:

I find the paragraph a little confusing. Saying certain elements will not be used in text generation may be a bit overstated, in that the generation of metadata may well become part of the process of generating the final text. It might be more correct to say "may not affect the rendering of the final text".  (And in the case of the example of index generation, I see that the text of this draft has an imbedded index--so I assume the related elements _were_ used in generating the text.

-- 1.1:

Is the section on changes from V2 intended to remain in the final RFC? Often such sections are removed, but there is info in here (esp 1.1.1) that may be useful in the long run.

-- 1.1, bulleted list of changes:

I find the past tense a bit confusing. I assume that the list represents incremental differences from V2, but the past tense made me wonder if it was meant as ways that V2 is different than V3.  (I suspect the author thought in terms of "changes that were made as we wrote this text", but I think the reader will think in terms of "changes this text makes to V2".

-- List entry for "postalline"

I had to stare at "postalline" for a while before I realized it meant "postal line" and not some sort of material, perhaps made from recycled mail (poh- stah-LEEN ). The point being that I find combined words like this very hard to read without some sort of separator or mixed case. Please consider that when creating new elements with compound word names. (e.g. <postal-line> or <postalLine> are much easier to read, for me at least.)

-- 1.1, 2nd paragraph, "less importantly"

I suggest dropping the value judgement. (I would personally find the lack of offline operation more of an issue than a need to change my anchor names, but that's just me.)

-- 2.5.8:

Please expand CJK on first use.

-- 2.40, series value table:

The value for 3GPP is "TBD". Is there an expectation that the RFC will have something real there?

-- 2.48, Content Model:

It might be worth marking deprecated elements. Otherwise a reader may not follow the xref to discover a legal child element is deprecated.

-- 2.58:

It might be helpful to mention what happens if an <xref> is _not_ empty.

---

From: Paul Hoffman <[email-masked]>
Date: Sat, 5 Apr 2014 18:10:16 -0700

Thanks for the review!

--Paul Hoffman

> Summary: This draft is on the right track. I have a few comments and questions that may or may not be worth consideration.

Yay!

> There are a few "to do" items left in the draft.  (Not surprising for an early review.)

Whacking away at them, yes.

> I find it confusing that we have two drafts in parallel, one for V2 that is obsoleted by this draft, and this draft for V3. With this draft copying much of V2 forward, which is authoritative?

Both. the v2 draft is authoritative for that version of the format (which is still in use); this draft will be definitive for v3 when v3 is implemented. Unlike a regular protocol, this format is not going to be immediately implemented when the draft goes to the RFC Editor.

> THANK YOU!!!! I think faking indented text using the <list> work around was one of the most annoying things about previous versions.

Hrm; I'm not used to seeing that in GenArt reviews. :-)

And, to be fair, lots of the new features have been suggested by many people on the RFC Editor's design team and in the bigger community.

> Can I have more than one of any given address sub-element? If so, how should it render?

Yep; unclear. There are a lot of things in this draft (and the in the v2 draft) where the rendering is undefined. We may or may not clarify those in the doc before we are finished; if not, it will be up to the programmers.

> If "height" ought to be avoided, should it be deprecated?

Yes; fixed.

> Also, what's the unit for height?

Deprecated. :-)

> (Same questions apply to "width")

Same answer. Also fixed.

> An example of how to use inlined graphics files might be helpful.

Will do, once we have a more stable definition of what SVG will be allowed. (You just added another open "to do" item.)

> -- 2.5.6:
> 
> A generic "code" value might be useful.

This would fall under "ascii-art".

> Otherwise, how do you expect these to be used? Syntax highlighting?

Probably not for the non-canonical versions, but some people will want to post-process the canonical XML to add syntax highlight, validation, and so on. The text above it says "A processor might add type-specific formatting to artwork with the preferred values in the non-canonical output formats."

> I assume the processor should never actually try to interpret code based on the "type" attribute. (Are there security considerations there?)

Correct, and yes. Added a security consideration about this.

> -- 2.7:
> 
> It seems like <b> (and also <i>)  is just as much format dependent as things like <width>. Wouldn't something like <em> be more useful for this purpose, where you have an abstract concept of emphasis that can be rendered differently for different formats?

In some senses, yes, but given that we know the main expected types of non-canonical output (HTML, PDF, EPUB), they all handle bold and italic and fixed-width fonts just fine. There are plenty of people who would think that "emphasis" means bold, and plenty who would think it means "italic".

> This seems like a place where our use cases are different than those for HTML, where markup is usually rendered by browsers that have similar font display capabilities.

No, our use cases very much align with HTML here: that's a design choice.

> In particular, what happens to <b>text<.b> when rendered into ASCII text?

Nothing. Just like today, there is a lot of formatting that is lost in the text output.

> Why does the "cite" attribute have different requirements than, say, xref? In particular, why wouldn't I want to cite a reference in the current doc, rather than a URL?

It can do both: the URL can be a fragment that points to a reference in the current doc.

> How would one reference an auto generated anchor identifier? If it doesn't exist until processing time...?

Correct, so you can't. You can only use "target" attributes to named anchors.

> What is the format for Month? Must you write it out? Abbreviate? Number?)

Whoops, that one was unclear. Fixed. (Will require the English spelling.)

> An example might be helpful

Good call; fixed.

> Is it possible to continue numbering from a previous list?

Not directly.

> The text says that "iprExtract" is used to reference a specific section.... Can you elaborate on how? E.g. do you reference an anchor? Are you allowed to have more than one "as-is" section?

Good question, and one I don't know the answer to right now. Another to-do listed.

> -- 2.44.2:
> 
> Why are numberless subsections disallowed?

If it was a sub-section, the heading could easily be mistaken for free text.

> It's pretty common to see documents that have non-numbered sub-heads inside numbered sections.

Those are probably "notes" and such, not real sections. Do you see a need for these? It's certainly possible to have them, but they seem more confusing than necessary to me.

Yes to both: they were added to <rfc> in the -05.

> Should the seriesInfo "name" values match the table from 2.40?

That's a good question, and is in play right now.

> Is it possible to select the symbol to be used for an unordered list?

Nope. That's a conscious design choice: the lists will look similar across RFCs.

> I wonder if the possibility of executable content existing in an RFC or draft is worth mention here? For an extreme example, see RFC6716, Appendix A. But more realistically, 2.5.5 mentions the poss…

Yup, and (as above) I added a paragraph about this.

> Also, does the need for a processor to potentially render binary content in general (in-lined or otherwise) expand the attack surface over that for previous versions of XML2RFC?

Not in any way I can think of.

> I find the paragraph a little confusing. Saying certain elements will not be used in text generation may be a bit overstated, in that the generation of metadata may well become part of the process…

Fixed.

> Is the section on changes from V2 intended to remain in the final RFC? Often such sections are removed, but there is info in here (esp 1.1.1) that may be useful in the long run.

Yes, it is intended to stay. It might move to an appendix, but it is important to list.

> I find the past tense a bit confusing. I assume that the list represents incremental differences from V2, but the past tense made me wonder if it was meant as ways that V2 is different than V3.  (I…

Good call. Fixed.

> I had to stare at "postalline" for a while before I realized it meant "postal line" and not some sort of material, perhaps made from recycled mail (poh- stah-LEEN ). The point being that I find com…

The latter. Fixed.

> I suggest dropping the value judgement. (I would personally find the lack of offline operation more of an issue than a need to change my anchor names, but that's just me.)

Fixed.

> Please expand CJK on first use.

Eeeps. Of course.

> The value for 3GPP is "TBD". Is there an expectation that the RFC will have something real there?

Yes. More research is obviously needed.

> It might be worth marking deprecated elements. Otherwise a reader may not follow the xref to discover a legal child element is deprecated.

These are automatically generated, and marking the deprecated ones is probably really really hard. We thought of this and punted.

> It might be helpful to mention what happens if an <xref> is _not_ empty.

Marked as another to-do.

Again: thanks! The things above marked as fixed or to-do will appear in the next draft.

---

From: Ben Campbell <[email-masked]>
Date: Mon, 7 Apr 2014 13:37:03 -0500

Hi, thanks for the quick response. Comments inline; sections that do not seem to need further comment are deleted, and marked with "[...]"

Thanks!

Ben.

On Apr 5, 2014, at 8:10 PM, Paul Hoffman <[email-masked]> wrote:

[...]

> Both. the v2 draft is authoritative for that version of the format (which is still in use); this draft will be definitive for v3 when v3 is implemented. Unlike a regular protocol, this format is no…

It's not clear to me that updates to "regular protocols" always get immediately implemented, at least not to the point of immediately replacing older version.  Especially we we are talking about formally incrementing version numbers.

I think my real question is whether V3 really obsoletes V2 in the usual sense. Do we allow further updates (e.g. an "updates" draft with bug fixes) to V2 once it becomes an RFC? If so, do those updates, assuming they impact "common" parts, affect V3? Would that be automatic, or would V3 require a parallel update? Do we intend to allow V2 to evolve independently of V3?

> And, to be fair, lots of the new features have been suggested by many people on the RFC Editor's design team and in the bigger community.

Okay, change that to THANK Y'ALL!!!!

> Yep; unclear. There are a lot of things in this draft (and the in the v2 draft) where the rendering is undefined. We may or may not clarify those in the doc before we are finished; if not, it will…

I accept that different rendering decisions might be okay. But would you also leave whether a specific sub-element can be repeated to the implementors? Seem like that could lead to xml2rfc "code" that is correct for one processor but incorrect for another.

[...]

> No, our use cases very much align with HTML here: that's a design choice.

Well, HTML _does_ have <em>. I realize it's not very useful in HTML, since you rarely render HTML to a format that can't do bold or italics. But to test the assertion, do you consider typesetting a common use case for HTML? Is it not one for xml2rfc?

> Nothing. Just like today, there is a lot of formatting that is lost in the text output.

There are some common conventions here; they just seemed to have fallen by the wayside. For example, a title of a long-format work gets italicized when that's supported, but underlined on an old fashioned typewriter. There are more modern simulations like _this_ and *this*.  

OTOH, I guess an ascii rendering processor could make those same choices for <i> and <b> as well as for <em>, so maybe I just countered my own argument. But from a typesetting perspective, abstractions like <em> allow one to separate the intent of the author ("I want this to be emphasized") from the intent of the editor/publisher.("This is how our 'style' renders emphasis.")

> It can do both: the URL can be a fragment that points to a reference in the current doc.

How would you do that? Is there a way to construct a URL that points to an xml2rfc anchor?

> Correct, so you can't. You can only use "target" attributes to named anchors.

If you can't reference an auto-generated anchor, why do you have them? What else do you do with anchors?

>> Is it possible to continue numbering from a previous list?

I may be misreading it, but doesn't V2 support number continuation with the "counter" attribute of <list>? If so, is the intent to remove that capability?

[...]

> Those are probably "notes" and such, not real sections. Do you see a need for these? It's certainly possible to have them, but they seem more confusing than necessary to me.

I've seen docs (not necessarily RFCs), that did something like this:

1. Heading
1.1 Subhead
1.1.1 Minor Subhead
(no number) Really Minor Subhead

I think the idea is to label deep sub-topics without the clutter of 1.1.1.1. Is it _necessary_? Probably not. But that's the use case I immediately envisioned when I thought about the ability to suppress numbering. 

[...]

> Not in any way I can think of.

For example (just thinking "out loud"), if a processor could insert JPEG artwork, does it need to worry about buffer overflow attacks on the JPEG format, as well as attacks on the xml itself? If so, does it matter if the artwork was in-lined vs referenced? 

[...]

> These are automatically generated, and marking the deprecated ones is probably really really hard. We thought of this and punted.

Okay.

---

From: Paul Hoffman <[email-masked]>
Date: Mon, 7 Apr 2014 12:42:54 -0700

Comment-on-comments below. I now have one new action item.

--Paul Hoffman

> I think my real question is whether V3 really obsoletes V2 in the usual sense. Do we allow further updates (e.g. an "updates" draft with bug fixes) to V2 once it becomes an RFC? If so, do those upd…

All good questions. I'll open a thread on rfc-interest with the question, but I strongly suspect it will end up having a non-answer.

> I accept that different rendering decisions might be okay. But would you also leave whether a specific sub-element can be repeated to the implementors? Seem like that could lead to xml2rfc "code" t…

Nope. The format is the format: it allows multiple sub-elements, and it would be wrong for a processor to reject an input based on that. It is probably fine for a processor to not render them all, although it would be better if it issued a warning. It would be best if we had rules for how processors should render each entity, but we haven't gone to that level of detail yet.

> Well, HTML _does_ have <em>. I realize it's not very useful in HTML, since you rarely render HTML to a format that can't do bold or italics. But to test the assertion, do you consider typesetting a…

No to both.

> OTOH, I guess an ascii rendering processor could make those same choices for <i> and <b> as well as for <em>, so maybe I just countered my own argument.

That was my first reaction. :-)

> But from a typesetting perspective, abstractions like <em> allow one to separate the intent of the author ("I want this to be emphasized") from the intent of the editor/publisher.("This is how our 'style' renders emphasis.")

In an ideal world where authors understood typesetting, yes. That's the world I began work in 35 years ago. (Cue the DEC formatting language theme music...) But that's not what is typical among IETF authors who are, not surprisingly, often literal-minded and goal-oriented.

> How would you do that? Is there a way to construct a URL that points to an xml2rfc anchor?

<blockquote cite="#anchorname">, I believe.

> If you can't reference an auto-generated anchor, why do you have them? What else do you do with anchors?

After the RFC is published, other documents can reference the anchor. Currently, the document only specifies this for <blockquote> and <cref>, but it has been mentioned for other elements as well.

> I may be misreading it, but doesn't V2 support number continuation with the "counter" attribute of <list>? If so, is the intent to remove that capability?

Yes and yes. Each list is free-standing. The need for continued numbering between lists in v2 is mostly obviated by allowing <t> in lists in v3. The semantics of "here is a second list whose numbers don't start at 1" are unclear, and we're trying to make v3 more semantically clearer. 

> I think the idea is to label deep sub-topics without the clutter of 1.1.1.1. Is it _necessary_? Probably not. But that's the use case I immediately envisioned when I thought about the ability to su…

Noted. I'd prefer to make all levels headings numbered if that's the overall style.

> For example (just thinking "out loud"), if a processor could insert JPEG artwork, does it need to worry about buffer overflow attacks on the JPEG format, as well as attacks on the xml itself? If so…

Um, maybe. I'm not at all sure how to word a security consideration about that that would be more useful than "a processor should not be stupid when doing includes".

---

From: Ben Campbell <[email-masked]>
Date: Mon, 7 Apr 2014 15:39:46 -0500

[...]

> Nope. The format is the format: it allows multiple sub-elements, and it would be wrong for a processor to reject an input based on that. It is probably fine for a processor to not render them all,…

Well, that was the original question--are multiple of the same sub-element allowed :-)

I guess a better followup question than "how do you render it" would be "are there cases where multiples of the same sub-type clearly does or does not make sense according to RFC style.

> In an ideal world where authors understood typesetting, yes. That's the world I began work in 35 years ago. (Cue the DEC formatting language theme music...) But that's not what is typical among IET…

Okay, I give in on this one.

> After the RFC is published, other documents can reference the anchor. Currently, the document only specifies this for <blockquote> and <cref>, but it has been mentioned for other elements as well.

I think this means that, at least for blockquote, even if you leave out anchor attribute in the xml, you will get whatever sort of identifier makes sense in the rendered output (e.g. an id attribute in HTML)? I read it to mean that the processor would auto generate a (perhaps ephemeral) anchor in the XML itself, which is not quite the same thing.

> Yes and yes. Each list is free-standing. The need for continued numbering between lists in v2 is mostly obviated by allowing <t> in lists in v3. The semantics of "here is a second list whose number…

Okay

> Noted. I'd prefer to make all levels headings numbered if that's the overall style.

Okay

> Um, maybe. I'm not at all sure how to word a security consideration about that that would be more useful than "a processor should not be stupid when doing includes".

Just as a strawman example:

Unlike previous versions, XML2RFC V3 allows the inclusion of potentially binary content via the "src" attribute of the <artwork> element. Processor implementors should bear in mind that such content may have vulnerabilities of its own. For example, certain JPEG renderers have been vulnerable to buffer-overflow attacks. An xml2rfc processor that allows the inclusion of artwork in JPEG format might be subject to buffer overrun attacks on both its XML parser and in its JPEG rendering code.

[...]

---

From: Paul Hoffman <[email-masked]>
Date: Mon, 7 Apr 2014 14:34:35 -0700

> I guess a better followup question than "how do you render it" would be "are there cases where multiples of the same sub-type clearly does or does not make sense according to RFC style.

I think they all probably make sense for some postal address format used somewhere in the world. The real question is whether we can guess how to sensibly render something with, say, two <city> elements. My guess is "no", and we'll end up telling the author to instead use a bunch of <postalLine> elements instead.

> I think this means that, at least for blockquote, even if you leave out anchor attribute in the xml, you will get whatever sort of identifier makes sense in the rendered output (e.g. an id attribut…

Correct, and this has convinced me to remove the auto-generation of anchors from <blockquote> and <cref>. (And, since writing last, I have discovered that even anchors to <cref> doesn't even render in the current xml2rfc, so that is of questionable value as well.

> Unlike previous versions, XML2RFC V3 allows the inclusion of potentially binary content via the "src" attribute of the <artwork> element. Processor implementors should bear in mind that such conten…

It really depends on what you mean by "binary". The v2 format supports inclusion of files in a few places already; a malicious submitter could make those files "binary". Further, a processor doesn't render anything: it puts out files. So, at best, the advice is "don't have a buffer overrun when including a file that you might output", which seems dumb. I'm still open to adding a security consideration, but I guess I feel it has to at least be marginally useful.

--Paul Hoffman

---

From: Ben Campbell <[email-masked]>
Date: Mon, 7 Apr 2014 17:02:51 -0500

"Okay" on all topics save the one below.

Thanks!

Ben.

On Apr 7, 2014, at 4:34 PM, Paul Hoffman <[email-masked]> wrote:

[...]

> It really depends on what you mean by "binary". The v2 format supports inclusion of files in a few places already; a malicious submitter could make those files "binary".

Were those files likely to be binary in normal usage? 

(I also note that the v2 security considerations are almost identical to the V3 ones, except for a disclaimer that they are probably incomplete :-)  )

> Further, a processor doesn't render anything: it puts out files.

That's an interesting point that I hadn't considered. I think it's probably true most of the time, but not all the time. On minimal thinking, I can imagine a processor that converts artwork to some preferred format. Or maybe some sort of just in time render that combines xml processing with direct display or printing.

> So, at best, the advice is "don't have a buffer overrun when including a file that you might output", which seems dumb. I'm still open to adding a security consideration, but I guess I feel it has to at least be marginally useful.

I still think it might be useful to say something to the effect of "While most of these security considerations apply to the interpreting of XML and rendering into various output formats, implementors may find that they are interpreting things other than XML, and should remember that those things may have additional security considerations".

The situation that seems most worthy of mention is that, if someone writes a processor that pulls in other (perhaps downloadable) libraries, plug-ins, OS functions, etc to process input beyond the XML itself,  they may inherit any security issues of those things. I realize that's a true statement about computing in general--but it seems more relevant for V3 processors than for previous versions. The fact that people keep finding vulnerabilities in such architectures suggests that the horse is not quite dead.

Obviously, this is all personal opinion, and carries no more weight than those of any other commenter (and probably less than those who have actually been working on updating xml2rfc).