jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: what motivates this ? Is it just the word minimum ? It changes from normative to non - normative which is a pretty big change and does n't reflect , imo , the consensus we had in singapore . 
 I see s mail now - but I think its in the rough at least with the current text being too strong ( rewording welcome ) . There was considerable discussion about h2 really being necessary to make this work well - there are just practical considerations to being able to always deploy that .. therefore SHOULD ( and the reason you would n't is its impractical to know or enforce version levels across a chain of infrastructure ) . 
 This sounds significant enough to be discussed on the list .
Paragraph (version A):
The minimum version of HTTP used by DOH SHOULD be HTTP/2 RFC7540.
Paragraph (version B):
HTTP/2 RFC7540 is the minimum RECOMMENDED version of HTTP for use
with DOH.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: This is OK , but I like the changes in better because it brings the " trust " discussion further forwards . Preferences ? 
 I prefer this PR over - changing from trust to authorization is more on point 
 I agree authorize is closer to the correct concept here but I 'd like to see a definition of it ( in a section of it 's own early in the document ) . But - I do n't believe there is an existing concept in DNS or DNSSEC that this is re - using ? Does ' authorize ' here mean that : the client will use all response from that server for resolution the client will cache all responses received from that server Also , if the trusted resolver itself is n't doing DNSSEC validation then the client 's cache can still be poisoned . The only 100 % sure method to stop cache poisoning is for the caching entity to perform DNSSEC validation .
Paragraph (version A):
Before using DOH response data for DNS resolution, the client MUST
establish that the HTTP request URI is a trusted service for the DOH
query.  For HTTP requests initiated by the DNS API client this trust
is implicit in the selection of URI.  For HTTP server push (RFC7540
Section 8.2) extra care must be taken to ensure that the pushed URI
is one that the client would have directed the same query to if the
client had initiated the request.  This specification does not extend
DNS resolution privileges to URIs that are not recognized by the
client as trusted DNS API servers.
Paragraph (version B):
Before using DOH response data for DNS resolution, the client MUST
establish that the HTTP request URI is authorized for the DOH query.
For HTTP requests initiated by the DNS API client this authorization
is implicit in the selection of URI.  For HTTP server push (RFC7540
Section 8.2) extra care must be taken to ensure that the pushed URI
is one that the client would have directed the same query to if the
client had initiated the request.  This specification does not extend
DNS resolution privileges to URIs that are not recognized by the
client as authorized DNS API servers.
Paragraph (version A):
A server that is acting both as a normal web server and a DNS API
server is in a position to choose which DNS names it forces a client
to resolve (through its web service) and also be the one to answer
those queries (through its DNS API service).  An untrusted DNS API
server can thus easily cause damage by poisoning a client's cache
with names that the DNS API server chooses to poison.  A client MUST
NOT trust a DNS API server simply because it was discovered, or
because the client was told to trust the DNS API server by an
untrusted party.  Instead, a client MUST only trust DNS API server
that is configured as trustworthy.
Paragraph (version B):
In the absence of information about the authenticity of responses,
such as DNSSEC, a DNS API server can poison a client's cache.  A
client MUST NOT authorize arbitrary DNS API servers.  Instead, a
client MUST specifically authorize DNS API servers using mechanisms
such as explicit configuration.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: unnecessary . The point here is to highlight the need to tweak the TTL to account for Age , not to go into why . It 's actually a generic requirement that is not specific to translation to other contexts .
Paragraph (version A):
A DOH response that was previously stored in an HTTP cache will
contain the RFC7234 Age response header indicating the elapsed time
between when the entry was placed in the HTTP cache and the current
DOH response.  DNS API clients should subtract this time from the DNS
TTL if they are re-sharing the information in a non HTTP context
(e.g., their own DNS cache) to determine the remaining time to live
of the DNS record.
Paragraph (version B):
A DOH response that was previously stored in an HTTP cache will
contain the RFC7234 Age response header indicating the elapsed time
between when the entry was placed in the HTTP cache and the current
DOH response.  DNS API clients should subtract this time from the DNS
TTL in each RRset to determine the time remaining on the TTL.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: This is n't necessary . I realize that this reverts a deliberate change as part of , but if it is important to describe - which I do n't think helps - then I do n't think that this is the right approach . Adding an explicit statement would be better . 
 hmm .. I think this was committed a little prematurely .. as  says , the change was originally deliberate to emphasize that uris are the primitive and not the server . Happy to make that an explicit statement - but do n't want to leave it out .
Paragraph (version A):
A server that supports this protocol on one or more URIs is called a
"DNS API server" to differentiate it from a "DNS server" (one that
uses the regular DNS protocol).  Similarly, a client that supports
this protocol is called a "DNS API client".
Paragraph (version B):
A server that supports this protocol is called a "DNS API server" to
differentiate it from a "DNS server" (one that uses the regular DNS
protocol).  Similarly, a client that supports this protocol is called
a "DNS API client".
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: When a statement is so definite , the reader tends to assume that there is something more to be said . In this case , the obvious question is " what other uses are there ? " , closely followed by " and what reason could the authors have had for not mentioning them ? "
Paragraph (version A):
Two primary uses cases were considered during this protocol's
development.  They included preventing on-path devices from
interfering with DNS operations and allowing web applications to
access DNS information via existing browser APIs in a safe way
consistent with Cross Origin Resource Sharing (CORS) CORS.  There are
certainly other uses for this work.
Paragraph (version B):
Two primary uses cases were considered during this protocol's
development.  They included preventing on-path devices from
interfering with DNS operations and allowing web applications to
access DNS information via existing browser APIs in a safe way
consistent with Cross Origin Resource Sharing (CORS) CORS.  No
special effort has been taken to enable or prevent application to
other use cases.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: The " using https:// URIs " part is just odd . Easier to simply state that this uses HTTPS at this level . Also , if the concept of a DNS service evolves to encompass other types of exchange than simple request - response , then " run DNS service " wo n't be accurate . 
 I " DOH " to the title because it was now being removed from the Abstract .
Paragraph (version A):
This document describes how to run DNS service over HTTP (DOH) using
https:// URIs.
Paragraph (version A):
This document defines a specific protocol for sending DNS RFC1035
queries and getting DNS responses over HTTP RFC7540 using https://
(and therefore TLS RFC5246 security for integrity and
confidentiality).  Each DNS query-response pair is mapped into a HTTP
exchange.
Paragraph (version B):
This document describes how to make DNS queries over HTTPS.
Paragraph (version B):
This document defines a specific protocol for sending DNS RFC1035
queries and getting DNS responses over HTTP RFC7540 using https URIs
(and therefore TLS RFC5246 security for integrity and
confidentiality).  Each DNS query-response pair is mapped into a HTTP
exchange.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: the removed text is inconsistent with the immediately preceding sentence . It can simply be removed .
Paragraph (version A):
This document does not change the definition of any HTTP response
codes or otherwise proscribe their use.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: this is meant as simpler alternative to . Its much less of a rewrite . consolidates caching rules by moving text adds a new section header " HTTP Exchange " for request and response to fall under moves the wireformat definition out of the http sections by moving text . 
 wdyt ? 
 I 'm not terribly happy with pushing the definition of wireformat to so much later because it will cause HTTP people to maybe miss the salient points . This makes the document feel much more like " HTTPS around DNS " instead of " DNS in HTTPS " , but I can live with it . Given that there are more knobs and fiddly bits in the HTTP part than in the DNS part , it 's reasonable to put those first . if you 're OK with it , say so here and I 'll accept . I 'll then make some very small editorial changes that I am seeing . 
 I 'm OK with it . Would putting the wire format first help ? FWIW I do n't think HTTP folks are going to miss bits just because of the position in the doc . 
 Thanks all . I think this is on balance a useful change . I 'll fix the bitrot and merge .
Paragraph (version A):
A server that supports this protocol is called a "DNS API server" to
differentiate it from a "DNS server" (one that uses the regular DNS
protocol).  Similarly, a client that supports this protocol is called
a "DNS API client".
Paragraph (version B):
A server that supports this protocol on one or more URIs is called a
"DNS API server" to differentiate it from a "DNS server" (one that
uses the regular DNS protocol).  Similarly, a client that supports
this protocol is called a "DNS API client".
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Hello , I am a non - native English speaker but I noticed the following sentence : " Earlier versions of HTTP are capable of conveying the semantic requirements of DOH but may result in very poor performance for many uses cases . " Should n't be there at the end ? Wiktionary ( ) suggests that plural of " use case " is " use cases " , not " uses cases " .
Paragraph (version A):
The messages in classic UDP based DNS RFC1035 are inherently
unordered and have low overhead.  A competitive HTTP transport needs
to support reordering, parallelism, priority, and header compression
to achieve similar performance.  Those features were introduced to
HTTP in HTTP/2 RFC7540.  Earlier versions of HTTP are capable of
conveying the semantic requirements of DOH but may result in very
poor performance for many uses cases.
Paragraph (version B):
The messages in classic UDP based DNS RFC1035 are inherently
unordered and have low overhead.  A competitive HTTP transport needs
to support reordering, parallelism, priority, and header compression
to achieve similar performance.  Those features were introduced to
HTTP in HTTP/2 RFC7540.  Earlier versions of HTTP are capable of
conveying the semantic requirements of DOH but may result in very
poor performance.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: dns request clarified in 
 From Star Brilliant on the DOH WG mailing list : Issue 1 : I found the phrase " URI template " is spelled with a lower " t " , where all other occurrences of this phrase is spelled with an upper " T " . Is this a typo ? Issue 2 : I suggest we change the word " and " in Line 2 to " or " , for the reason that an HTTP request could not be both GET and POST .
Paragraph (version A):
The URI template defined in this document is processed without any
variables for requests using POST, and with the single variable "dns"
for requests using GET.  The value of the dns parameter is the
content of the request (as described in dnswire), encoded with
base64url RFC4648.
Paragraph (version B):
The URI Template defined in this document is processed without any
variables when the HTTP method is POST.  When the HTTP method is GET
the single variable "dns" is defined as the content of the request
(as described in dnswire), encoded with base64url RFC4648.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: The fact that an HTTP server can provide a response in the format of its choice was not well understood by DNS people . This motivates the MTI format for servers . 
 On 2018 - 03 - 25 , sent the following to the list : At the meeting in London last week , we asked the room for opinions on two topics : we have a content - type that is Mandatory to Implement ? Several participants spoke in favor of making the default format ( currently called " application / dns - udpwireformat " ) mandatory , at least for servers . the GET and POST modes of operation , which , if any , should be mandatory to implement ? Among the participants , there was consensus in favor of making both GET and POST mandatory to implement for servers . If you would like to voice a dissenting opinion on either point , please reply on this list . Otherwise , the chairs will regard these decisions as the group 's consensus . 
 See PR 
 I think most of this can be handled by the MTI PR . But I will just make a tiny clarification indicating that the server is really able to return whatever it needs to .
Paragraph (version A):
The DNS API client SHOULD include an HTTP "Accept:" request header to
say what type of content can be understood in response.  The client
MUST be prepared to process "application/dns-udpwireformat" dnswire
responses but MAY process any other type it receives.
Paragraph (version B):
The DNS API client SHOULD include an HTTP "Accept" request header to
indicate what type of content can be understood in response.
Irrespective of the value of the Accept request header, the client
MUST be prepared to process "application/dns-udpwireformat" dnswire
responses but MAY also process any other type it receives.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Please do n't include advice about TLS extensions that are n't deployed . RFC 6961 is not widely implemented or used . I 'm sad to say , but RFC 6066 is the best reference for OCSP stapling right now . Also , if you are including this sort of advice , advice against using AIA should go there as well . Some browsers chase AIA URLs in certificates , which will fail for similar reasons . ( You can cite Section 4.2.2.1 of RFC 5280 for that bit ) . 
 Given that this has wandered around a bit , could you create a PR with exactly the changes to the Operational Considerations that you think are needed here ?
Paragraph (version A):
Some HTTPS client implementations perform real time third party
checks of the revocation status of the certificates being used by
TLS.  If this check is done as part of the DNS API server connection
procedure and the check itself requires DNS resolution to connect to
the third party a deadlock can occur.  The use of an OCSP RFC6960
server is one example of how this deadlock can happen.  To avoid the
possibility of deadlock, DNS API servers SHOULD bundle the
certificate status as part of the handshake using a mechanism
appropriate to the version of TLS, such as using RFC6961 for TLS
version 1.2.
Paragraph (version B):
Some HTTPS client implementations perform real time third party
checks of the revocation status of the certificates being used by
TLS.  If this check is done as part of the DNS API server connection
procedure and the check itself requires DNS resolution to connect to
the third party a deadlock can occur.  The use of OCSP RFC6960
servers or AIA for CRL fetching (RFC5280 Section 4.2.2.1) are
examples of how this deadlock can happen.  To mitigate the
possibility of deadlock, DNS API servers SHOULD bundle the
certificate status as part of the handshake using a mechanism
appropriate to the version of TLS, such as using RFC6066 Section 8
for TLS version 1.2.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: By my unofficial informal tally , there was a strong agreement on application / dns - udpwireformat being mandatory , and both GET and POST mandatory for servers . 
 I made some very minor edits merge if you 're ok with them 
 The fact that an HTTP server can provide a response in the format of its choice was not well understood by DNS people . This motivates the MTI format for servers . 
 On 2018 - 03 - 25 , sent the following to the list : At the meeting in London last week , we asked the room for opinions on two topics : we have a content - type that is Mandatory to Implement ? Several participants spoke in favor of making the default format ( currently called " application / dns - udpwireformat " ) mandatory , at least for servers . the GET and POST modes of operation , which , if any , should be mandatory to implement ? Among the participants , there was consensus in favor of making both GET and POST mandatory to implement for servers . If you would like to voice a dissenting opinion on either point , please reply on this list . Otherwise , the chairs will regard these decisions as the group 's consensus . 
 See PR 
 I think most of this can be handled by the MTI PR . But I will just make a tiny clarification indicating that the server is really able to return whatever it needs to . 
 as discussed on list .. 1 ) Make one mandatory - to - implement 2 ) Make both mandatory - to - implement 3 ) Talk about why there is no mandatory - to - implemen 
 At the face - to - face meeting , I thought the sense of the room was servers MUST implement both GET and POST , clients can implement either or both . This needs to be confirmed on the list . 
 See PR 
 My personal take of consensus is that , having heard no opposition to the position of summary above , to go with that .
Paragraph (version B):
DNS API servers MUST implement both POST and GET methods.
Paragraph (version B):
In order to maximize interoperability, DNS API clients and DNS API
servers MUST support the "application/dns-udpwireformat" media type.
Other media types MAY be used as defined by HTTP Content Negotiation
(RFC7231 Section 3.4).
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: This is to address the issue of draft - ietf - dnsop - dns - wireformat - http needing to say what the original transport was . Covered on the mailing list March 25 and March 30 . 
 What 's the benefit of " original _ " over just plain " transport " ?
Paragraph (version B):
This protocol does not define any use for the "original_transport"
optional parameter of the application/dns-udpwireformat media type.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: my previous ( deleted now ) comment was in error in case you get a copy of that in email . sorry - git skillz failure on my part .
Paragraph (version A):
The queries and responses must be able to be flexible enough to
express every normal DNS query.
Paragraph (version B):
The queries and responses must be able to be flexible enough to
express every DNS query that would normally be sent in DNS over
UDP (including queries and responses that use DNS extensions, but
not those that require multiple responses).
Paragraph (version A):
The protocol must ensure interoperability by specifying a single
format for requests and responses that is mandatory to implement.
That format must be able to support future modifications to the
DNS protocol including the inclusion of one or more EDNS
extensions (including those not yet defined).
Paragraph (version B):
The protocol must ensure interoperability by specifying a single
format for requests and responses that is mandatory to implement.
That format must be able to support future modifications to the
DNS protocol including the inclusion of one or more EDNS options
(including those not yet defined).
Paragraph (version A):
DNS API clients using the DNS wire format MAY have one or more EDNS
extensions RFC6891 in the request.
Paragraph (version B):
DNS API clients using the DNS wire format MAY have one or more EDNS
options RFC6891 in the request.
Paragraph (version A):
The DNS response for "application/dns-udpwireformat" in dnswire MAY
have one or more EDNS extensions, depending on the extension
definition of the extensions given in the DNS request.
Paragraph (version B):
The DNS response for "application/dns-udpwireformat" in dnswire MAY
have one or more EDNS options, depending on the extension definition
of the extensions given in the DNS request.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: hmm . we do need to fix this - but the proposed fix removes a normative should and introduces tls 1.3 which creates a publishing dependency . The dep is rather minor , but the benefit to DoH even more minor . let me see if I can come up with a fix that is just a SHOULD inline / staple 
 We can not say SHOULD use 6961 because that is not allowed in TLS 1.3 . I purposely did n't make a publishing dependency to TLS 1.3 by naming it but not giving a link ; every reader of this document will know what we are talking about . 
 I understand the problem . We can probably say something like SHOULD generically staple or inline ( such as 6961 where it applies ) . tls 1.3 does do stapling , it just does n't do it via 6961 . 
 wdyt of that ? 
 Reworded again , and back to you 
 " DNS API servers SHOULD utilize OCSP Stapling [ RFC6961 ] to provide the client with certificate revocation information that does not require contacting a third party . " TLS 1.3 will probably be published before DOH and TLS 1.3 deprecates / obsoletes RFC 6961 . TLS 1.3 uses only RFC 6066 . Maybe you should refer to both RFC 6066 and RFC 6961 . 
 Good catch ! Open as PR .
Paragraph (version A):
Many HTTPS implementations perform real time third party checks of
the revocation status of the certificates being used by TLS.  If this
check is done as part of the DNS API server connection procedure and
the check itself requires DNS resolution to connect to the third
party a deadlock can occur.  The use of an OCSP RFC6960 server is one
example of how this can happen.  DNS API servers SHOULD utilize OCSP
Stapling RFC6961 to provide the client with certificate revocation
information that does not require contacting a third party.
Paragraph (version B):
Some HTTPS client implementations perform real time third party
checks of the revocation status of the certificates being used by
TLS.  If this check is done as part of the DNS API server connection
procedure and the check itself requires DNS resolution to connect to
the third party a deadlock can occur.  The use of an OCSP RFC6960
server is one example of how this deadlock can happen.  To avoid the
possibility of deadlock, DNS API servers SHOULD bundle the
certificate status as part of the handshake using a mechanism
appropriate to the version of TLS, such as using RFC6961 for TLS
version 1.2.