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

Commentary: Separate out confidentiality and authentication - -01 said " Running DNS over HTTPS relies on the security of the underlying HTTP connection . " This PR clarifies that the HTTPS connection can only provide confidentiality and authentication of the DNS API server . Clients wanting authentic DNS answers need to perform DNSSEC validation or explicitly trust the DNS API server . 
 I reverted this because my comment above was not satisfied before merge . 
 pr did some of this but was backed out . see that diff and discussion 
 I agree with the notion of separating transport security from e2e validation .. but I think the changes overshoot a touch . I would leave the first paragraph alone - https provides more than confidentiality and I do n't think the text suggests anything other than doh relies on https . I like your second paragraph - though if we leave the first one in tact you probably want to remove the " also authenticates " part .. it can be recast as transport security between api server and client vs e2e validation
Paragraph (version A):
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 B):
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):
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: closes issue 
 thanks . 
 The draft says " the HTTP cache headers SHOULD be set to expire at the same time as the shortest DNS TTL in the response " , which might not be strong enough . A SHOULD might be OK for shorter , but allowing the value to increase might be unwise , depending on the caching model . 
 agree 
 Seems like it should be MUST : 
 some typos , also , I ca n't seem to parse 1 of the sentence .
Paragraph (version A):
In the HTTP responses, the HTTP cache headers SHOULD be set to expire
at the same time as the shortest DNS TTL in the response.  Because
DNS provides only caching but not revalidation semantics, DNS over
HTTP responses should not carry revalidation response headers (such
as Last-Modified: or Etag:) or return 304 responses.
Paragraph (version B):
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):
A DNS API Client that receives a response without an explicit
freshness lifetime MUST NOT assign that response a heuristic
freshness (RFC7234 Section 4.2.2.) greater than that indicated by the
DNS Record with the smallest TTL in the response.
Paragraph (version B):
Because DNS provides only caching but not revalidation semantics, DNS
over HTTP responses should not carry revalidation response headers
(such as Last-Modified: or Etag:) or return 304 responses.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: proposed to close issue 
 thanks 
 If it is n't then including it in an example might be unwise . Explicitly pointing out that it is currently fictitious might avoid confusion . 
 some typos
Paragraph (version A):
For 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 JSON-based content type.
Paragraph (version A):
The examples uses HTTP/2 formatting from RFC7540.
Paragraph (version B):
These examples use HTTP/2 style formatting from RFC7540.
Paragraph (version B):
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.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: And explain why more clearly . 
 this is editorial - should me merged imo 
 I fully disagree that making something a RFC 2119 requirement is " editorial " . In this case , it could have surprising effects on the DNS server side of a DOH server . It 's worth discussing , but not just sweeping it in with " editorial " . 
 when I wrote that text I meant it to be SHOULD - its a typo ; that 's why its editorial :) If its not normative then it really has no meaning in that paragraph .
Paragraph (version A):
In order to maximize cache friendliness, DNS API clients using media
formats that include DNS ID, such as application/dns-udpwireformat,
should use a DNS ID of 0 in every DNS request.  HTTP semantics
correlate the request and response, thus eliminating the need for the
ID in a media type such as application/dns-udpwireformat.
Paragraph (version B):
In order to maximize cache friendliness, DNS API clients using media
formats that include DNS ID, such as application/dns-udpwireformat,
SHOULD use a DNS ID of 0 in every DNS request.  HTTP correlates
request and response, thus eliminating the need for the ID in a media
type such as application/dns-udpwireformat and the use of a varying
DNS ID can cause semantically equivalent DNS queries to be cached
separately.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: Firstly , mention that the URI can be anything . Then explain why the well - known exists . The well - known URI exists for two reasons : aid in discovery , for cases where the discovery process produces only a domain name ( or domain name and port ) contextualize server pushes The first does n't need a SHOULD . 
 The draft gets stuck into describing pieces of the URL , but neglects to point out some obvious things , like what the URL is for . It could probably use some more clarity about the configuration and discovery point as well .
Paragraph (version A):
The path SHOULD be "/.well-known/dns-query" but a different path can
be used if the DNS API Client has prior knowledge about a DNS API
service on a different path at the origin being used.  (See iana for
the registration of this in the well-known URI registry.)  Using the
well-known path allows automated discovery of a DNS API Service, and
also helps contextualize DNS Query requests pushed over an active
HTTP/2 connection.
Paragraph (version B):
To make a DNS API query, a DNS API client sends an HTTP request to
the URI of the DNS API.
Paragraph (version B):
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.
Draft: draft-ietf-doh-dns-over-https-latest

Commentary: I think that we should specify behaviour for truncated responses with the TC bit more clearly . Right now the text is a little vague . There seem to be three options : the generation of an HTTP error the forwarding of the truncated response allow either the use of truncated responses and recommend fallback to TCP if the DNS API server is just making DNS requests to another server I think that the draft current vacilates in the direction of 3 , but I tend to like 1 or 4 . Choosing 4 would n't be consistent with the dnsop DNS - over - HTTP draft using DOH though . 
 is the right answer , so the text should just be stronger about it . If DOH requires or , that means that the DNS server code will need to be heavily reworked to capture these from going out , which seems pointless . DOH clients can act like normal stubs : either they do or do n't know about truncation and  . 
 I agree - I do n't think doh needs to behave differently here than any other datagram based client - i.e. its not a transport error . can you do a pr to clarify ? 
 Will do .
Paragraph (version A):
The primary use case is to prevent on-path network devices from
interfering with native DNS operations.  This interference includes,
but is not limited to, spoofing DNS responses, blocking DNS requests,
and tracking.  HTTP authentication and proxy friendliness are
expected to make this protocol function in some environments where
DNS directly on TLS (RFC7858) would not.
Paragraph (version B):
The primary use case is to prevent on-path network devices from
interfering with native DNS operations.  This interference includes,
but is not limited to, spoofing DNS responses, blocking DNS requests,
and tracking.  HTTP authentication and proxy friendliness are
expected to make this protocol function in some environments where
unsecured DNS (DNS) or DNS directly on TLS (RFC7858) would not.