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

Commentary: I think I managed to make this a tad tighter .. merge it if you agree 
 Some people reading the document thought that it only applied to the two use cases given , and could not be used for other things . It might be good to just pare it down to its essentials and move it as a sub - section of the Introduction . See PR . 
 closed by 76
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.  There are
certainly other uses for this work.
Paragraph (version A):
There are two initial use cases for this protocol.
Paragraph (version A):
The primary use case is to prevent on-path network devices from
interfering with DNS operations.  This interference includes, but is
not limited to, spoofing DNS responses, blocking DNS requests, and
tracking.
Paragraph (version A):
In this use, clients - whether operating systems or individual
applications - will be explicitly configured to use a DOH server as a
recursive resolver by its user (or administrator).  They might use
the DOH server for all queries, or only for a subset of them.  The
specific configuration mechanism is out of scope for this document.
Paragraph (version A):
A secondary use case is allowing web applications to access DNS
information, by using existing APIs in browsers to access it over
HTTP in a safe way consistent with Cross Origin Resource Sharing
(CORS) CORS.
Paragraph (version A):
This is technically already possible (since the server controls both
the HTTP resources it exposes and the use of browser APIs by its
content), but standardization might make this easier to accomplish.
Paragraph (version A):
Note that in this second use, the browser does not consult the DOH
server or use its responses for any DNS lookups outside the scope of
the application using them; i.e., there is (currently) no API that
allows a Web site to poison DNS for others.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Also remove extraneous comment about discovery in the charter
Paragraph (version A):
The working group will analyze the security and privacy issues that
could arise from accessing DNS over HTTPS.  In particular, the
working group will consider the interaction of DNS and HTTP caching.
Paragraph (version B):
caching describes the interaction of this protocol with HTTP caching.
An adversary that can control the cache used by the client can affect
that client's view of the DNS.  This is no different than the
security implications of HTTP caching for other protocols that use
HTTP.
Paragraph (version A):
The working group may define mechanisms for discovery of DOH servers
similar to existing mechanisms for discovering other DNS servers if
the chairs determine that there is both sufficient interest and
working group consensus.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: I 've seen an implementation report that confused  and base64url ; they noted that the examples did n't include one where the distinction was important 
 yes , there is also the bit about not having the sign paddings that caught me at first . During the DOH proxy implementation , I missed the padding part . I have it implemented in and I think it is correct :) Would an example implementation in a language be worth adding to the examples ? It may be more straightforward to read than examples . documentation says : This may be worth highlighting as what base64url is too . 
 This is complicated by the fact that some people want the encoding of responses to GET to be media - type - specific . 
 I think you mean GET request body parameters ( not responses - which are always in bodies and not encoded ) 
 Yes , I meant body parameters . 
 Please stop calling the parameter . It 's really confusing . ( I just read this and thought to myself " GET does n't have a body " ) . 
 note that the current encoded url in the github copy is wrong as it was n't updated when the dns i d changed to 0 . I 'll fix that as part of making a base 64 example .
Paragraph (version A):
These examples use a DNS API service located at
https://dnsserver.example.net/dns-query.  The requests are
represented as application/dns-udpwirefomat typed bodies, but the
client indicates it can parse responses in either that format or as a
hypothetical JSON-based content type.  The application/simpledns+json
type used by this example is currently fictitious.
Paragraph (version B):
These examples use a DNS API service located at
https://dnsserver.example.net/dns-query to resolve the IN A records.
Paragraph (version B):
The requests are represented as application/dns-udpwirefomat typed
bodies, but the client indicates it can parse responses in either
that format or as a hypothetical JSON-based content type.  The
application/simpledns+json type used by this example is currently
fictitious.
Paragraph (version B):
Finally, a GET based query for a.62characterlabel-makes-base64url-
distinct-from-standard-base64.example.com is shown as an example to
emphasize that the encoding alphabet of base64url is different than
regular base64 and that padding is omitted.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: and 
 The draft says : But it probably needs to describe at least one way to perform that automated discovery . It 's probably not a good idea to have people attempt to guess . 
 fwiw the .wk is used here so that that when a request / response pair is pushed the client understands this to be DoH. Its probably also helpful to have a well - known path here for the normal so that defaults of https:// , 443 , and the default path can be used in configuration systems that might only be capable of a hostname . ( e.g. my DoH server is at ) .. I 'll work on text . 
 I think I can future proof for the context I want using a response header instead of a well known .. imo that 's kind of ignoring the point of the path - but whatever . Maybe I 'll propose x - well - known :)
Paragraph (version A):
To make a DNS API query, a DNS API client sends an HTTP request to
the URI of the DNS API.
Paragraph (version A):
The URI scheme MUST be https.
Paragraph (version A):
A client can be configured with a DNS API URI, or it can discover the
URI.  This document defines a well-known URI path of "/.well-known/
dns-query" so that a discovery process that produces a domain name or
domain name and port can be used to construct the DNS API URI.  (See
iana for the registration of this in the well-known URI registry.)
DNS API servers SHOULD use this well-known path to help contextualize
DNS Query requests that use server push RFC7540.
Paragraph (version A):
A DNS API Client encodes a single DNS query into the HTTP request
using either the HTTP GET or POST methods.
Paragraph (version B):
To make a DNS API query a DNS API client encodes a single DNS query
into an HTTP request using either the HTTP GET or POST method and the
other requirements of this section.  The DNS API server defines the
URI used by the request.  Configuration and discovery of the URI is
done out of band from this protocol.
Paragraph (version A):
For this example assume a DNS API server is following this
specification on origin https://dnsserver.example.net/ and the well-
known path.  The DNS API client chooses to send its requests in
application/dns-udpwirefomat but indicates it can parse replies in
that format or as a hypothetical JSON-based content type.  The
application/simpledns+json type used by this example is currently
fictitious.
Paragraph (version B):
These examples use a DNS API service located at
https://dnsserver.example.net/dns-query.  The requests are
represented as application/dns-udpwirefomat typed bodies, but the
client indicates it can parse responses in either that format or as a
hypothetical JSON-based content type.  The application/simpledns+json
type used by this example is currently fictitious.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: closes issue 
 this is an evolution of
Paragraph (version A):
When using the GET method the URI path MUST contain a query parameter
with the name of "body".  The value of the parameter is the content
of the request encoded with base64url RFC4648.  Using the GET method
is friendlier to many HTTP cache implementations.
Paragraph (version B):
When using the GET method the URI path MUST contain a query parameter
with the name of "body".  The value of the parameter is the content
of the request potentially encoded with base64url RFC4648.
Specifications that define media types for use with DOH, such as DNS
Wire Format dnswire of this document, MUST indicate if the body
parameter uses base64url encoding.
Paragraph (version B):
Using the GET method is friendlier to many HTTP cache
implementations.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Right now the text only defines that future edns options must be supported , but ( IMHO ) we should support all future versions of changes to the DNS in general , not just future EDNS extensions . So I proposed text that rewords a bit to state this and uses EDNS as an example . 
 Good call . There might be other on - the - wire extension mechanisms in the future .
Paragraph (version A):
The protocol must ensure interoperable media formats through a
mandatory to implement format wherein a query must be able to
contain one or more EDNS extensions, including those not yet
defined.
Paragraph (version B):
The protocol must ensure interoperable media formats through a
mandatory to implement format wherein a query must be able to
contain future modifications to the DNS protocol including the
inclusion of one or more EDNS extensions (including those not yet
defined).
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: ( IMHO )
Paragraph (version A):
When using the POST method, the body is not encoded.
Paragraph (version B):
When using the POST method, the body MUST NOT be encoded.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: This text is rather subjective without data . Changing it to " may " still brings the point without needing a reference to a study proving the sentence true . 
 ( whoops ; just realized I 've been blowing my pull requests by chaining them off a single branch ... my bad , and this will cause you some pain )
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 acheive 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 would 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 acheive 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.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Unfortunately , we should n't use the existing real - world address and should be using example ip space instead . 
 unfortunately you included the PR changes in this PR too .. let 's see if the merge process can sort that out :) 
 ok ! thanks .
Paragraph (version A):
This is an example response for a query for the IN A records for
"www.example.com" with recursion turned on.  The response bears one
record with an address of 93.184.216.34 and a TTL of 128 seconds.
Paragraph (version B):
This is an example response for a query for the IN A records for
"www.example.com" with recursion turned on.  The response bears one
record with an address of 192.0.2.1 and a TTL of 128 seconds.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: minor editoral changes 
 thanks for these . The only one that 's a little iffy is the inclusion of the reason phrase for 415 ... but I think here its giving more explanatory value than an impression that particular phrase needs to be used ( which would n't jibe with http details ) .
Paragraph (version A):
This is technically already possible (since the server controls both
the HTTP resources it exposes and the use of browser APIs by its
content), but standardisation might make this easier to accomplish.
Paragraph (version B):
This is technically already possible (since the server controls both
the HTTP resources it exposes and the use of browser APIs by its
content), but standardization might make this easier to accomplish.
Paragraph (version A):
The protocol must use a secure transport that meets the
requirements for modern HTTPS.
Paragraph (version B):
The protocol must use a secure transport that meets the
requirements for HTTPS.
Paragraph (version A):
When using the GET method the URI path MUST contain a query parameter
with the name of ct and a value indicating the media-format used for
the body parameter.  The value may either be an explicit media type
(e.g. ct=application/dns-udpwireformat&body=...) or it may be empty.
An empty value indicates the default application/dns-udpwireformat
type (e.g. ct&body=...).
Paragraph (version A):
When using the GET method the URI path MUST contain a query parameter
with the name of body.  The value of the parameter is the content of
the request encoded with base64url RFC4648.  Using the GET method is
friendlier to many HTTP cache implementations.
Paragraph (version B):
When using the GET method the URI path MUST contain a query parameter
with the name of "ct" and a value indicating the media-format used
for the body parameter.  The value may either be an explicit media
type (e.g. ct=application/dns-udpwireformat&body=...) or it may be
empty.  An empty value indicates the default application/dns-
udpwireformat type (e.g. ct&body=...).
Paragraph (version B):
When using the GET method the URI path MUST contain a query parameter
with the name of "body".  The value of the parameter is the content
of the request encoded with base64url RFC4648.  Using the GET method
is friendlier to many HTTP cache implementations.
Paragraph (version A):
At the time this is published, the response types are works in
progress.  The only known response type is "application/dns-
udpwireformat", but it is possible that at least one JSON-based
response format will be defined in the future.
Paragraph (version B):
At the time this is published, the response types are works in
progress.  The only response type defined in this document is
"application/dns-udpwireformat", but it is possible that at least one
JSON-based response format will be defined in the future.
Paragraph (version A):
A DNS API Server SHOULD respond with HTTP status code 415 upon
receiving a media type it is unable to process.
Paragraph (version B):
A DNS API Server SHOULD respond with HTTP status code 415
(Unsupported Media Type) upon receiving a media type it is unable to
process.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: In order to prevent a dependency on traditional DNS or a DNS query for CRL / OCSP certificate validation check , OCSP stapling should be used for the HTTPS web server . 
 we 're probably better off describing the potential deadlock in revocation and mentioning stapling as a best practice .. but in general I think we want to stay away from specifying a whole lot of how - to - profile - https details as these things do differ between clients and we tend to accept all of the variants as "  " .. for e.g.
Paragraph (version B):
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.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: … 
 during the singapore meeting tale noted that the http caching model , where 1 lifetime is assigned to the rrset is not necessarily the way a dns cache would handle things .. each rr can have its own ttl ( though one dns implementation does it this way ) . perhaps worth some explanatory text when talking about rrset granularity and http caches .
Paragraph (version A):
The Answer section of a DNS response contains one or more RRsets.
(RRsets are defined in RFC7719.)  According to RFC2181, each resource
record in an RRset is supposed to have the Time To Live (TTL)
freshness information.  Different RRsets in the Answer section can
have different TTLs.  The HTTP response freshness lifetime (RFC7234
Section 4.2) should be coordinated with the Resource Record bearing
the smallest TTL in the Answer section of the response.  The HTTP
freshness lifetime SHOULD be set to expire at the same time any of
the DNS Records reach a 0 TTL.  The response freshness lifetime MUST
NOT be greater than that indicated by the DNS Record with the
smallest TTL in the response.
Paragraph (version B):
The Answer section of a DNS response contains one or more RRsets.
(RRsets are defined in RFC7719.)  According to RFC2181, each resource
record in an RRset is supposed to have the Time To Live (TTL)
freshness information.  Different RRsets in the Answer section can
have different TTLs, though it is only possible for the HTTP response
to have a single freshness lifetime.  The HTTP response freshness
lifetime (RFC7234 Section 4.2) should be coordinated with the
Resource Record bearing the smallest TTL in the Answer section of the
response.  The HTTP freshness lifetime SHOULD be set to expire at the
same time any of the DNS Records reach a 0 TTL.  The response
freshness lifetime MUST NOT be greater than that indicated by the DNS
Record with the smallest TTL in the response.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: pr did some of this but was backed out . see that diff and discussion
Paragraph (version B):
The HTTPS connection provides transport security for the interaction
between the DNS API server and client, but does not inherently ensure
the authenticity of DNS data.  A DNS API client may also perform full
DNSSEC validation of answers received from a DNS API server or it may
choose to trust answers from a particular DNS API server, much as a
DNS client might choose to trust answers from its recurvise DNS
resolver.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Reverts dohwg / draft - ietf - doh - dns - over - https
Paragraph (version A):
DNS over HTTPS relies on the underlying HTTPS connection to provide
confidentiality.  By requiring at least RFC7540 levels of support for
TLS, this protocol expects to use current best practices for
confidential transport.
Paragraph (version B):
Running DNS over HTTPS relies on the security of the underlying HTTP
connection.  By requiring at least RFC7540 levels of support for TLS,
this protocol expects to use current best practices for secure
transport.
Paragraph (version A):
The HTTPS connection also authenticates the DNS API server but does
not inherently assure of authenticity of DNS data.  A DNS API client
may choose to trust answers from a particular DNS API server, much as
a DNS client might choose to trust answers from its recurvise DNS
resolver.  A DNS API client may also perform full DNSSEC validation
of answers received from a DNS API server.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: recently I 've left the ack section mostly untouched until the final ( or near final ) edit . Easier to deal with it once . However I think its good idea to have leave the PR open and amend it as useful 
 OK , having a " living " PR seems OK .
Paragraph (version A):
Joe Hildebrand contributed lots of material for a different iteration
of this document.  Helpful early comments were given by Ben Schwartz
and Mark Nottingham.
Paragraph (version B):
This work required a high level of cooperation between experts in
different technologies.  Thank you Ray Bellis, Stephane Bortzmeyer,
Manu Bretelle, Tony Finch, Daniel Kahn Gilmor, Olafur Guomundsson,
Wes Hardaker, Rory Hewitt, Joe Hildebrand, David Lawrence, Eliot
Lear, John Mattson, Alex Mayrhofer, Mark Nottingham, Jim Reid, Adam
Roach, Ben Schwartz, Davey Song, Daniel Stenberg, Andrew Sullivan,
Martin Thomson, and Sam Weiler.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: … issue 
 It is not stated crystal clear in the -01 draft if there 's only one DNS packet per HTTP request or if it is allowed to send more than one . Some wordings ( like ) suggest a single packet . I think it would benefit the document to be more explicit on this detail . 
 good point - it is meant to be one , otherwise blocking and reordering ( which is resolved at the intra - request http level ) would be a problem . we 'll add text .
Paragraph (version A):
This document defines a specific protocol for sending DNS RFC1035
queries and getting DNS responses over modern versions of HTTP
RFC7540 using https:// (and therefore TLS RFC5246 security for
integrity and confidentiality).
Paragraph (version B):
This document defines a specific protocol for sending DNS RFC1035
queries and getting DNS responses over modern versions of HTTP
RFC7540 using https:// (and therefore TLS RFC5246 security for
integrity and confidentiality).  Each DNS query-response pair is
mapped into a HTTP request-response pair.
Paragraph (version A):
A DNS API Client encodes the DNS query into the HTTP request using
either the HTTP GET or POST methods.
Paragraph (version B):
A DNS API Client encodes a single DNS query into the HTTP request
using either the HTTP GET or POST methods.
Paragraph (version A):
A DNS response may contain a set of DNS Resource Records each with
its own Time To Live (TTL) freshness information.  The freshness
lifetime (RFC7234 Section 4.2) of the HTTP response should be
coordinated with the Resource Record bearing the smallest TTL in the
response.  The freshness lifetime SHOULD be set to expire at the same
time any of the DNS Records reach a 0 TTL.  The response freshness
lifetime MUST NOT be greater than that indicated by the DNS Record
with the smallest TTL in the response.
Paragraph (version B):
The Answer section of a DNS response contains one or more RRsets.
(RRsets are defined in RFC7719.)  According to RFC2181, each resource
record in an RRset is supposed to have the Time To Live (TTL)
freshness information.  Different RRsets in the Answer section can
have different TTLs.  The HTTP response freshness lifetime (RFC7234
Section 4.2) should be coordinated with the Resource Record bearing
the smallest TTL in the Answer section of the response.  The HTTP
freshness lifetime SHOULD be set to expire at the same time any of
the DNS Records reach a 0 TTL.  The response freshness lifetime MUST
NOT be greater than that indicated by the DNS Record with the
smallest TTL in the response.