Draft: draft-ietf-doh-dns-over-https-latest

Commentary: This issue is here just so we do n't lose it ; the discussion is happening on the mailing list under the subject line that contains " terminology : " DNS API " " 
 Fixed by
Paragraph (version A):
A server that supports this protocol is called a "DNS API server" to
differentiate it from a "DNS server" (one that only provides DNS
service over one or more of the other transport protocols
standardized for DNS).  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 "DoH server" to
differentiate it from a "DNS server" (one that only provides DNS
service over one or more of the other transport protocols
standardized for DNS).  Similarly, a client that supports this
protocol is called a "DoH client".
Paragraph (version A):
Configuration, discovery, and updating of the URI Template RFC6570
(see httprequest) is done out of band from this protocol.  Note that
configuration might be manual (such as a user typing URI Templates in
a user interface for "options") or automatic (such as URI Templates
being supplied in responses from DHCP or similar protocols).  DNS API
Servers MAY support more than one URI.  This allows the different
endpoints to have different properties such as different
authentication requirements or service level guarantees.
Paragraph (version A):
A DNS API client uses configuration to select the URI, and thus the
DNS API server, that is to be used for resolution.  RFC2818 defines
how HTTPS verifies the DNS API server's identity.
Paragraph (version A):
A DNS API client MUST NOT use a different URI simply because it was
discovered outside of the client's configuration, or because a server
offers an unsolicited response that appears to be a valid answer to a
DNS query.  This specification does not extend DNS resolution
privileges to URIs that are not recognized by the DNS API client as
configured URIs.  Such scenarios may create additional operational,
tracking, and security hazards that require limitations for safe
usage.  A future specification may support this use case.
Paragraph (version B):
Configuration, discovery, and updating of the URI Template RFC6570
(see httprequest) is done out of band from this protocol.  Note that
configuration might be manual (such as a user typing URI Templates in
a user interface for "options") or automatic (such as URI Templates
being supplied in responses from DHCP or similar protocols).  DoH
Servers MAY support more than one URI.  This allows the different
endpoints to have different properties such as different
authentication requirements or service level guarantees.
Paragraph (version B):
A DoH client uses configuration to select the URI, and thus the DoH
server, that is to be used for resolution.  RFC2818 defines how HTTPS
verifies the DoH server's identity.
Paragraph (version B):
A DoH client MUST NOT use a different URI simply because it was
discovered outside of the client's configuration, or because a server
offers an unsolicited response that appears to be a valid answer to a
DNS query.  This specification does not extend DNS resolution
privileges to URIs that are not recognized by the DoH client as
configured URIs.  Such scenarios may create additional operational,
tracking, and security hazards that require limitations for safe
usage.  A future specification may support this use case.
Paragraph (version A):
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 through the use of a URI Template.
Paragraph (version B):
A DoH 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 DoH server defines the URI used by the request through
the use of a URI Template.
Paragraph (version A):
DNS API servers MUST implement both the POST and GET methods.
Paragraph (version B):
DoH servers MUST implement both the POST and GET methods.
Paragraph (version A):
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-message" (as described
in dnswire) responses but MAY also process any other type it
receives.
Paragraph (version A):
In order to maximize cache friendliness, DNS API clients using media
formats that include DNS ID, such as application/dns-message, SHOULD
use a DNS ID of 0 in every DNS request.  HTTP correlates the request
and response, thus eliminating the need for the ID in a media type
such as application/dns-message.  The use of a varying DNS ID can
cause semantically equivalent DNS queries to be cached separately.
Paragraph (version A):
DNS API clients can use HTTP/2 padding and compression in the same
way that other HTTP/2 clients use (or don't use) them.
Paragraph (version A):
These examples use a DNS API service with a URI Template of
"https://dnsserver.example.net/dns-query{?dns}" to resolve IN A
records.
Paragraph (version B):
The DoH 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-message" (as described
in dnswire) responses but MAY also process any other type it
receives.
Paragraph (version B):
In order to maximize cache friendliness, DoH clients using media
formats that include DNS ID, such as application/dns-message, SHOULD
use a DNS ID of 0 in every DNS request.  HTTP correlates the request
and response, thus eliminating the need for the ID in a media type
such as application/dns-message.  The use of a varying DNS ID can
cause semantically equivalent DNS queries to be cached separately.
Paragraph (version B):
DoH clients can use HTTP/2 padding and compression in the same way
that other HTTP/2 clients use (or don't use) them.
Paragraph (version B):
These examples use a DoH service with a URI Template of
"https://dnsserver.example.net/dns-query{?dns}" to resolve IN A
records.
Paragraph (version A):
The only response type defined in this document is "application/dns-
message", but it is possible that other response formats will be
defined in the future.  A DNS API server MUST be able to process
application/dns-message request messages.
Paragraph (version B):
The only response type defined in this document is "application/dns-
message", but it is possible that other response formats will be
defined in the future.  A DoH server MUST be able to process
application/dns-message request messages.
Paragraph (version A):
HTTP responses with non-successful HTTP status codes do not contain
replies to the original DNS question in the HTTP request.  DNS API
clients need to use the same semantic processing of non-successful
HTTP status codes as other HTTP clients.  This might mean that the
DNS API client retries the query with the same DNS API server, such
as authorization failures (HTTP status code 401 RFC7235 Section 3.1).
It could also mean that the DNS API client retries with a different
DNS API server, such as for unsupported media types (HTTP status code
415, RFC7231 Section 6.5.13), or where the server cannot generate a
representation suitable for the client (HTTP status code 406, RFC7231
Section 6.5.6), and so on.
Paragraph (version B):
HTTP responses with non-successful HTTP status codes do not contain
replies to the original DNS question in the HTTP request.  DoH
clients need to use the same semantic processing of non-successful
HTTP status codes as other HTTP clients.  This might mean that the
DoH client retries the query with the same DoH server, such as
authorization failures (HTTP status code 401 RFC7235 Section 3.1).
It could also mean that the DoH client retries with a different DoH
server, such as for unsupported media types (HTTP status code 415,
RFC7231 Section 6.5.13), or where the server cannot generate a
representation suitable for the client (HTTP status code 406, RFC7231
Section 6.5.6), and so on.
Paragraph (version A):
A DOH exchange can pass through a hierarchy of caches that include
both HTTP and DNS specific caches.  These caches may exist beteen the
DNS API server and client, or on the DNS API client itself.  HTTP
caches are by design generic; that is, they do not understand this
protocol.  Even if a DNS API client has modified its cache
implementation to be aware of DOH semantics, it does not follow that
all upstream caches (for example, inline proxies, server-side
gateways and Content Delivery Networks) will be.
Paragraph (version A):
As a result, DNS API servers need to carefully consider the HTTP
caching metadata they send in response to GET requests (POST requests
are not cacheable unless specific response headers are sent; this is
not widely implemented, and not advised for DOH).
Paragraph (version A):
In particular, DNS API servers SHOULD assign an explicit freshness
lifetime (RFC7234 Section 4.2) so that the DNS API client is more
likely to use fresh DNS data.  This requirement is due to HTTP caches
being able to assign their own heuristic freshness (such as that
described in RFC7234 Section 4.2.2), which would take control of the
cache contents out of the hands of the DNS API server.
Paragraph (version B):
A DoH exchange can pass through a hierarchy of caches that include
both HTTP and DNS specific caches.  These caches may exist beteen the
DoH server and client, or on the DoH client itself.  HTTP caches are
by design generic; that is, they do not understand this protocol.
Even if a DoH client has modified its cache implementation to be
aware of DoH semantics, it does not follow that all upstream caches
(for example, inline proxies, server-side gateways and Content
Delivery Networks) will be.
Paragraph (version B):
As a result, DoH servers need to carefully consider the HTTP caching
metadata they send in response to GET requests (POST requests are not
cacheable unless specific response headers are sent; this is not
widely implemented, and not advised for DoH).
Paragraph (version B):
In particular, DoH servers SHOULD assign an explicit freshness
lifetime (RFC7234 Section 4.2) so that the DoH client is more likely
to use fresh DNS data.  This requirement is due to HTTP caches being
able to assign their own heuristic freshness (such as that described
in RFC7234 Section 4.2.2), which would take control of the cache
contents out of the hands of the DoH server.
Paragraph (version A):
DNS API servers also need to consider caching when generating
responses that are not globally valid.  For instance, if a DNS API
server customizes a response based on the client's identity, it would
not want to allow global reuse of that response.  This could be
accomplished through a variety of HTTP techniques such as a Cache-
Control max-age of 0, or by using the Vary response header (RFC7231
Section 7.1.4) to establish a secondary cache key (RFC7234
Section 4.1).
Paragraph (version A):
DNS API clients MUST account for the Age response header's value
(RFC7234) when calculating the DNS TTL of a response.  For example,
if a RRset is received with a DNS TTL of 600, but the Age header
indicates that the response has been cached for 250 seconds, the
remaining lifetime of the RRset is 350 seconds.
Paragraph (version A):
DNS API clients can request an uncached copy of a response by using
the "no-cache" request cache control directive (RFC7234,
Section 5.2.1.4) and similar controls.  Note that some caches might
not honor these directives, either due to configuration or
interaction with traditional DNS caches that do not have such a
mechanism.
Paragraph (version B):
DoH servers also need to consider caching when generating responses
that are not globally valid.  For instance, if a DoH server
customizes a response based on the client's identity, it would not
want to allow global reuse of that response.  This could be
accomplished through a variety of HTTP techniques such as a Cache-
Control max-age of 0, or by using the Vary response header (RFC7231
Section 7.1.4) to establish a secondary cache key (RFC7234
Section 4.1).
Paragraph (version B):
DoH clients MUST account for the Age response header's value
(RFC7234) when calculating the DNS TTL of a response.  For example,
if a RRset is received with a DNS TTL of 600, but the Age header
indicates that the response has been cached for 250 seconds, the
remaining lifetime of the RRset is 350 seconds.
Paragraph (version B):
DoH clients can request an uncached copy of a response by using the
"no-cache" request cache control directive (RFC7234, Section 5.2.1.4)
and similar controls.  Note that some caches might not honor these
directives, either due to configuration or interaction with
traditional DNS caches that do not have such a mechanism.
Paragraph (version A):
Before using DOH response data for DNS resolution, the client MUST
establish that the HTTP request URI may be used for the DOH query.
For HTTP requests initiated by the DNS API client this 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.
Paragraph (version A):
In order to maximize interoperability, DNS API clients and DNS API
servers MUST support the "application/dns-message" media type.  Other
media types MAY be used as defined by HTTP Content Negotiation
(RFC7231 Section 3.4).  Those media types MUST 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 B):
Before using DoH response data for DNS resolution, the client MUST
establish that the HTTP request URI may be used for the DoH query.
For HTTP requests initiated by the DoH client this 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.
Paragraph (version B):
In order to maximize interoperability, DoH clients and DoH servers
MUST support the "application/dns-message" media type.  Other media
types MAY be used as defined by HTTP Content Negotiation (RFC7231
Section 3.4).  Those media types MUST 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):
DNS API clients using this media type MAY have one or more EDNS
options RFC6891 in the request.  DNS API servers using this media
type MUST ignore the value given for the EDNS UDP payload size in DNS
requests.
Paragraph (version B):
DoH clients using this media type MAY have one or more EDNS options
RFC6891 in the request.  DoH servers using this media type MUST
ignore the value given for the EDNS UDP payload size in DNS requests.
Paragraph (version A):
Session level encryption has well known weaknesses with respect to
traffic analysis which might be particularly acute when dealing with
DNS queries.  HTTP/2 provides further advice about the use of
compression (RFC7540 Section 10.6) and padding (RFC7540 Section 10.7
).  DNS API Servers can also add DNS padding RFC7830 if the DNS API
requests it in the DNS query.
Paragraph (version A):
The HTTPS connection provides transport security for the interaction
between the DNS API server and client, but does not provide the
response integrity of DNS data provided by DNSSEC.  DNSSEC and DOH
are independent and fully compatible protocols, each solving
different problems.  The use of one does not diminish the need nor
the usefulness of the other.  It is the choice of a client to either
perform full DNSSEC validation of answers or to trust the DNS API
server to do DNSSEC validation and inspect the AD (Authentic Data)
bit in the returned message to determine whether an answer was
authentic or not.  As noted in http-response, different response
media types will provide more or less information from a DNS response
so this choice may be affected by the response media type.
Paragraph (version B):
Session level encryption has well known weaknesses with respect to
traffic analysis which might be particularly acute when dealing with
DNS queries.  HTTP/2 provides further advice about the use of
compression (RFC7540 Section 10.6) and padding (RFC7540 Section 10.7
).  DoH Servers can also add DNS padding RFC7830 if the DoH requests
it in the DNS query.
Paragraph (version B):
The HTTPS connection provides transport security for the interaction
between the DoH server and client, but does not provide the response
integrity of DNS data provided by DNSSEC.  DNSSEC and DoH are
independent and fully compatible protocols, each solving different
problems.  The use of one does not diminish the need nor the
usefulness of the other.  It is the choice of a client to either
perform full DNSSEC validation of answers or to trust the DoH server
to do DNSSEC validation and inspect the AD (Authentic Data) bit in
the returned message to determine whether an answer was authentic or
not.  As noted in http-response, different response media types will
provide more or less information from a DNS response so this choice
may be affected by the response media type.
Paragraph (version A):
In the absence of DNSSEC information, a DNS API server can give a
client invalid data in response to a DNS query. selection disallows
the use of DOH DNS responses that do not originate from configured
servers.  This prohibition does not guarantee protection against
invalid data, but it does reduce the risk.
Paragraph (version B):
In the absence of DNSSEC information, a DoH server can give a client
invalid data in response to a DNS query. selection disallows the use
of DoH DNS responses that do not originate from configured servers.
This prohibition does not guarantee protection against invalid data,
but it does reduce the risk.
Paragraph (version A):
The HTTPS channel used by this specification establishes secure two
party communication between the DNS API client and the DNS API
server.  Filtering or inspection systems that rely on unsecured
transport of DNS will not function in a DNS over HTTPS environment.
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 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 NOT rely on DNS based
references to external resources in the TLS handshake.  For OCSP the
server can 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.  AIA deadlocks can be avoided
by providing intermediate certificates that might otherwise be
obtained through additional requests.  Note that these deadlocks also
need to be considered for server that a DNS API server might redirect
to.
Paragraph (version A):
A DNS API client may face a similar bootstrapping problem when the
HTTP request needs to resolve the hostname portion of the DNS URI.
Just as the address of a traditional DNS nameserver cannot be
originally determined from that same server, a DNS API client cannot
use its DNS API server to initially resolve the server's host name
into an address.  Alternative strategies a client might employ
include making the initial resolution part of the configuration, IP
based URIs and corresponding IP based certificates for HTTPS, or
resolving the DNS API server's hostname via traditional DNS or
another DNS API server while still authenticating the resulting
connection via HTTPS.
Paragraph (version A):
A DNS API server is allowed to answer queries with any valid DNS
response.  For example, a valid DNS response might have the TC
(truncation) bit set in the DNS header to indicate that the server
was not able to retrieve a full answer for the query but is providing
the best answer it could get.  A DNS API server can reply to queries
with an HTTP error for queries that it cannot fulfill.  In this same
example, a DNS API server could use an HTTP error instead of a non-
error response that has the TC bit set.
Paragraph (version B):
The HTTPS channel used by this specification establishes secure two
party communication between the DoH client and the DoH server.
Filtering or inspection systems that rely on unsecured transport of
DNS will not function in a DNS over HTTPS environment.
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 DoH 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, DoH servers SHOULD NOT rely on DNS based
references to external resources in the TLS handshake.  For OCSP the
server can 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.  AIA deadlocks can be avoided
by providing intermediate certificates that might otherwise be
obtained through additional requests.  Note that these deadlocks also
need to be considered for server that a DoH server might redirect to.
Paragraph (version B):
A DoH client may face a similar bootstrapping problem when the HTTP
request needs to resolve the hostname portion of the DNS URI.  Just
as the address of a traditional DNS nameserver cannot be originally
determined from that same server, a DoH client cannot use its DoH
server to initially resolve the server's host name into an address.
Alternative strategies a client might employ include making the
initial resolution part of the configuration, IP based URIs and
corresponding IP based certificates for HTTPS, or resolving the DNS
API server's hostname via traditional DNS or another DoH server while
still authenticating the resulting connection via HTTPS.
Paragraph (version B):
A DoH server is allowed to answer queries with any valid DNS
response.  For example, a valid DNS response might have the TC
(truncation) bit set in the DNS header to indicate that the server
was not able to retrieve a full answer for the query but is providing
the best answer it could get.  A DoH server can reply to queries with
an HTTP error for queries that it cannot fulfill.  In this same
example, a DoH server could use an HTTP error instead of a non-error
response that has the TC bit set.