;; Implementation of a DoH-client, see RFC 8484 (DNS Queries over
;; HTTPS (DoH))
(in-package #:dns)
;; The DoH client is configured with a URI Template [RFC6570]
(defvar *doh-base-url* "https://dns.google/dns-query"
"Base URL of the service providing DNS-over-HTTP(S). Defaults to the
Google-hosted API.")
(defun lookup-generic (name type)
(multiple-value-bind (stream)
(drakma:http-request *doh-base-url*
:decode-content t
:want-stream t
:parameters `(("type" . ,type)
("name" . ,name)
("ct" . "application/dns-message")))
(read-binary 'dns-message stream)))
(defun lookup-txt (name)
"Look up the TXT records at NAME."
(lookup-generic name "TXT"))
(defun lookup-mx (name)
"Look up the MX records at NAME."
(lookup-generic name "MX"))
;; 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 DNS
;; request (as described in Section 6), encoded with base64url
;; [RFC4648].
;; When using the POST method, the DNS query is included as the message
;; body of the HTTP request, and the Content-Type request header field
;; indicates the media type of the message. POSTed requests are
;; generally smaller than their GET equivalents.
;; Using the GET method is friendlier to many HTTP cache
;; implementations.
;; The DoH client SHOULD include an HTTP Accept request header field to
;; indicate what type of content can be understood in response.
;; Irrespective of the value of the Accept request header field, the
;; client MUST be prepared to process "application/dns-message" (as
;; described in Section 6) responses but MAY also process other DNS-
;; related media types it receives.
;; In order to maximize HTTP cache friendliness, DoH clients using media
;; formats that include the ID field from the DNS message header, 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.
;; DoH clients can use HTTP/2 padding and compression [RFC7540] in the
;; same way that other HTTP/2 clients use (or don't use) them.
;; 4.1.1. HTTP Request Examples
;; These examples use HTTP/2-style formatting from [RFC7540].
;; These examples use a DoH service with a URI Template of
;; "https://dnsserver.example.net/dns-query{?dns}" to resolve IN A
;; records.
;; The requests are represented as bodies with media type "application/
;; dns-message".
;; The first example request uses GET to request "www.example.com".
;; :method = GET
;; :scheme = https
;; :authority = dnsserver.example.net
;; :path = /dns-query?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB
;; accept = application/dns-message
;; 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.
;; 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.
;; Each DNS request-response pair is mapped to one HTTP exchange.
;; DNS response codes indicate either success or failure for the DNS
;; query. A successful HTTP response with a 2xx status code (see
;; Section 6.3 of [RFC7231]) is used for any valid DNS response,
;; 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.
;; 4.2.2. HTTP Response Example
;; This is an example response for a query for the IN AAAA records for
;; "www.example.com" with recursion turned on. The response bears one
;; answer record with an address of 2001:db8:abcd:12:1:2:3:4 and a TTL
;; of 3709 seconds.
;; :status = 200
;; content-type = application/dns-message
;; content-length = 61
;; cache-control = max-age=3709
;; <61 bytes represented by the following hex encoding>
;; 00 00 81 80 00 01 00 01 00 00 00 00 03 77 77 77
;; 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 00 1c 00
;; 01 c0 0c 00 1c 00 01 00 00 0e 7d 00 10 20 01 0d
;; b8 ab cd 00 12 00 01 00 02 00 03 00 04
;; This protocol MUST be used with the https URI scheme [RFC7230].
;; In particular, DoH servers SHOULD assign an explicit HTTP freshness
;; lifetime (see Section 4.2 of [RFC7234]) 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 Section 4.2.2 of [RFC7234]), which would take
;; control of the cache contents out of the hands of the DoH server.
;; The assigned freshness lifetime of a DoH HTTP response MUST be less
;; than or equal to the smallest TTL in the Answer section of the DNS
;; response. A freshness lifetime equal to the smallest TTL in the
;; Answer section is RECOMMENDED. For example, if a HTTP response
;; carries three RRsets with TTLs of 30, 600, and 300, the HTTP
;; freshness lifetime should be 30 seconds (which could be specified as
;; "Cache-Control: max-age=30"). This requirement helps prevent expired
;; RRsets in messages in an HTTP cache from unintentionally being
;; served.
;; If the DNS response has no records in the Answer section, and the DNS
;; response has an SOA record in the Authority section, the response
;; freshness lifetime MUST NOT be greater than the MINIMUM field from
;; that SOA record (see [RFC2308]).
;; DoH clients MUST account for the Age response header field's value
;; [RFC7234] when calculating the DNS TTL of a response. For example,
;; if an RRset is received with a DNS TTL of 600, but the Age header
;; field indicates that the response has been cached for 250 seconds,
;; the remaining lifetime of the RRset is 350 seconds. This requirement
;; applies to both DoH client HTTP caches and DoH client DNS caches.
;; 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.
;; In order to maximize interoperability, DoH clients and DoH servers
;; MUST support the "application/dns-message" media type.
;; The data payload for the "application/dns-message" media type is a
;; single message of the DNS on-the-wire format defined in Section 4.2.1
;; of [RFC1035], which in turn refers to the full wire format defined in
;; Section 4.1 of that RFC.
;; This media type restricts the maximum size of the DNS message to
;; 65535 bytes.
;; When using the GET method, the data payload for this media type MUST
;; be encoded with base64url [RFC4648] and then provided as a variable
;; named "dns" to the URI Template expansion. Padding characters for
;; base64url MUST NOT be included.
;; When using the POST method, the data payload for this media type MUST
;; NOT be encoded and is used directly as the HTTP message body.
