Last Call Review of draft-ietf-stir-identity-header-errors-handling-05
review-ietf-stir-identity-header-errors-handling-05-artart-lc-duerst-2022-11-04-00
Request | Review of | draft-ietf-stir-identity-header-errors-handling |
---|---|---|
Requested revision | No specific revision (document currently at 08) | |
Type | Last Call Review | |
Team | ART Area Review Team (artart) | |
Deadline | 2022-11-03 | |
Requested | 2022-10-20 | |
Authors | Chris Wendt | |
I-D last updated | 2022-11-04 | |
Completed reviews |
Genart Last Call review of -05
by Stewart Bryant
(diff)
Artart Last Call review of -05 by Martin J. Dürst (diff) |
|
Assignment | Reviewer | Martin J. Dürst |
State | Completed | |
Request | Last Call review on draft-ietf-stir-identity-header-errors-handling by ART Area Review Team Assigned | |
Posted at | https://mailarchive.ietf.org/arch/msg/art/Jqiy69abgnAMBuSH7oLpt1Ae62I | |
Reviewed revision | 05 (document currently at 08) | |
Result | Ready w/issues | |
Completed | 2022-11-04 |
review-ietf-stir-identity-header-errors-handling-05-artart-lc-duerst-2022-11-04-00
In my opinion, this document is not ready for publication as is, but it could be made ready rather soon if the issues it has get fixed. The topic of the document seems to be straightforward, although I don't know the actual technology. It's also not clear what software will do that doesn't know about the new protocol constructs introduced in this document (i.e., it's not clear whether and in what way these constructs are backwards compatible; I'm assuming the WG has thought about that, but specific cases may be worth mentioning in the document). The main issues I found are two: 1) The title is too general. 2) There are a lot of long(winded) sentences that are difficult to read. Details: - The title is too general. Identity headers could appear (in the future) in email or http or any other protocol. Please expand to something like "Identity Header Errors Handling for STIR". - There are many sentences that are too long and too complicated. This starts in the abstract, which consists only of two very long sentences. Some authors (including myself) have a tendency to write long sentences. That means that they have to be extra careful to do an additional pass on their documents and fix all sentences that are too long. My own personal guideline is that everything above two lines is too long. Sometimes, it is easy for an editor to fix such long sentences, but given the highly technical content of this document, this has to be done by the author or somebody else very close to the subject matter. Without consistently keeping sentence level below a certain threshold, and checking and fixing all sentences again for complexity, this document should not be passed to the RFC editor. (long/complex sentences in the rest of the document are not mentioned individually) [Also, some paragraphs are very long, in particular in Section 5 and Section 9. These would benefit from splitting up.] - In the introduction, a very short summary of the overall architecture as it relates to the details in this document should be given. This should in particular explain the concepts of "authentication service" and "verification" (A naive reader such as this one did assume that it is the authentication service that does the verification, but the text in Section 5 seems to indicate otherwise.) - Introduction: " This specification provides some additional mechanisms for solutions to address these problems.": Please say how many additional mechanisms, and what they are. (What they are is potentially discussed in the next two paragraphs, but this could be worked out better.) - Section 6: It should be stated more clearly that there is one Reason header field per error (or what otherwise the numeric relationship between Reason header fields and errors is). - Section 6: Is the cause always 436? If yes, say so (and why), if not, provide an example (or more) with another cause. - Section 9: "where there is multiple identity header errors" -> "where there are multiple identity header errors" - Section 9, last sentence: "use of the compact form can avoid many of the security and privacy concerns": "many of" is a bit vague. - Occasionally, articles are missing (e.g. "Jon Peterson, Roman Shpount, Robert Sparks and STIR working group" -> "Jon Peterson, Roman Shpount, Robert Sparks and the STIR working group")