Hi Martin,
Thank you very much for your comprehensive review, i have addressed your comments in the newly submitted 06 draft, details inline.
On Nov 4, 2022, at 9:39 AM, Martin Dürst via Datatracker <noreply@xxxxxxxx> wrote:
Reviewer: Martin Dürst
Review result: Ready with Issues
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".
Agree with qualifying it with STIR, fixed.
- 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.]
Yes, thanks, I will definitely admit I am guilty of long sentences, I did a pass at breaking things 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.)
Agree to both of the above, re-wrote many parts of the introduction.
- 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).
Fixed
- Section 6: Is the cause always 436? If yes, say so (and why), if not, provide
an example (or more) with another cause.
Fixed
- Section 9: "where there is multiple identity header errors" -> "where there
are multiple identity header errors"
Fixed
- Section 9, last sentence: "use of the compact form can avoid many of the
security and privacy concerns": "many of" is a bit vague.
Fixed
- 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”)
Fixed
