Skip to content

[1.1.1.1] Add warning about lack of RFC for DoH JSON format #19756

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 6, 2025
Merged

[1.1.1.1] Add warning about lack of RFC for DoH JSON format #19756

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
81bccf5
[1.1.1.1] Add warning about lack of RFC for DoH JSON format
SebastiaanYN Feb 5, 2025
231ab99
Minor style guide adjustments
RebeccaTamachiro Feb 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions src/content/docs/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@ title: Using JSON
slug: 1.1.1.1/encryption/dns-over-https/make-api-requests/dns-json
---

:::caution
The DNS over HTTPS JSON format does not have a formal RFC, which means behavior might be different between providers. Additionally, there might be small changes in behavior in the future.

For critical use cases, it is recommended to use the [DNS over HTTPS wireformat](/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-wireformat/), which is defined in [RFC 1035](https://www.rfc-editor.org/rfc/rfc1035.html).
:::

Cloudflare's DNS over HTTPS endpoint also supports JSON format for querying DNS data. For lack of an agreed upon JSON schema for DNS over HTTPS in the Internet Engineering Task Force (IETF), Cloudflare has chosen to follow the same schema as Google's DNS over HTTPS resolver.
Copy link
Contributor

@hannes-cf hannes-cf Feb 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wondering if we should phrase this a bit more generally like

(...) chosen to follow the same schema as Google's DNS over HTTPS resolver other common public resolvers' DNS over HTTPS implementation. 🤔


JSON formatted queries are sent using a `GET` request. When making requests using `GET`, the DNS query is encoded into the URL. The client should include an HTTP `Accept` request header field with a MIME type of `application/dns-json` to indicate that the client is able to accept a JSON response from the DNS over HTTPS resolver.
Expand Down
2 changes: 1 addition & 1 deletion ...ent/docs/1.1.1.1/encryption/dns-over-https/make-api-requests/dns-wireformat.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ head:
slug: 1.1.1.1/encryption/dns-over-https/make-api-requests/dns-wireformat
---

Cloudflare respects DNS wireformat as defined in [RFC 1035](https://datatracker.ietf.org/doc/html/rfc1035).
Cloudflare respects DNS wireformat as defined in [RFC 1035](https://www.rfc-editor.org/rfc/rfc1035.html).
Copy link
Contributor

@hannes-cf hannes-cf Feb 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@SebastiaanYN can we point to certain section in this RFC that contains the specifics we're following here? Like section 7. RESOLVER IMPLEMENTATION

Copy link
Contributor Author

@SebastiaanYN SebastiaanYN Feb 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case we're referring to the RFC as a whole because it's about the data format, which is defined in multiple sections of the RFC (2/3/4)

Copy link
Contributor

@hannes-cf hannes-cf Feb 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

okay, then let's keep it as suggested 👍


To send queries using DNS wireformat, set the header `accept: application/dns-message`, or `content-type: application/dns-message` if using `POST` to signalize the media type of the query.

Expand Down