AdGuard DNS now supports Structured DNS Errors. Here’s what it means

November 6, 2024 4 min read

The AdGuard DNS v2.10 release is comparable in scope to the DNS-over-QUIC implementation — AdGuard DNS has once again become the world’s first public DNS resolver to implement a new feature before it becomes an official standard. This time, it’s Structured DNS Errors.

Below, we’ll go into detail about what this is and why it’s important. But if you’re short on time, here’s the summary:

When a website is blocked at the DNS level, users may see a “This site can’t be reached” or “No Internet connection” error that doesn’t explain the reason for the block.
To clarify this, DNS servers could redirect users to their own page with an explanation. However, HTTPS websites (which are the majority of websites) would require a separate certificate.
There’s a simpler solution: Structured DNS Errors (SDE). They allow additional information (like the reason for blocking, responsible entity, and contact info) to be sent in the DNS response so that the browser can read it and pass it on to the user, greatly improving communication transparency.
For this system to work, browsers must start supporting SDE. This is what we’re advocating for.

What Structured DNS Errors are: A detailed look

DNS-level filtering is widely used. AdGuard DNS alone has over 100 million users. People use DNS filtering to block ads and trackers or to protect their children. Even if a user hasn’t set up DNS manually, they still encounter DNS filtering — due to their country’s or company’s policies. It’s safe to assume that nearly as many people have encountered DNS-blocked websites as there are Internet users.

DNS-level blocking prevents access to an entire domain. A user tries to visit https://example.com, their browser makes a DNS request, and a DNS server responds that the domain example.com is blocked, causing the browser to display “This site can’t be reached” or “No Internet connection”.

"This site can't be reached" error

If the user hasn’t manually blocked this domain, they may not understand why they can’t open the page. They might wonder:

Is something wrong? Should I reload the page?
That didn’t work. Is the Internet connection down?
The Internet is fine. Is the page blocked? Yes, but why?
Maybe my DNS service is down. I should report it.

This lack of communication between the DNS service and the user is a problem. DNS services can and want to solve this — for example, by redirecting the user to a page with a more detailed explanation so they know what happened and who to contact.

Why not just do that?

There’s a catch:

If it’s an HTTP website, meaning the connection isn’t encrypted, the DNS server can safely redirect the user to an unencrypted page.
If it’s an HTTPS website, the browser performs certificate authentication and expects to see a valid certificate for https://example.com. If AdGuard DNS redirects to its own page, the browser will throw a certificate validation error.

Certificate error

One solution is to install a special certificate on the user’s device. However, this isn’t always possible or secure. There’s a much easier way — send more information in the DNS response.

To achieve this, the 2020 Extended DNS Errors standard was introduced, enabling DNS responses to include an error code along with an EXTRA-TEXT field for further details. The Structured DNS Errors draft also proposes adding I-JSON (a restricted profile of JSON) files to the EXTRA-TEXT field that browsers can easily read and display in a user-friendly format.

What would these I-JSON files contain?

Reason for blocking
Contact information for inquiries if the page was blocked by mistake
Organization responsible for DNS filtering in this case (optional)
Other optional information

This is really convenient. Such a system enhances transparency between DNS services and users and keeps users secure. If they understand why a website is blocked, they’re less likely to abandon a secure DNS server for an unencrypted one.

What it takes to implement Extended DNS Errors and Structured DNS Errors

Browsers must support them. After all, they determine what information the user sees — whether it’s just a connection error or a detailed explanation of why the website is blocked and what to do next.

So here we call on browser representatives to add support for RFC 8914 and ideally its proposed update. This change will help make the Internet more transparent and user-friendly for billions of people.

What it looks like in AdGuard DNS

We’ve created a demo extension that shows how Structured DNS Errors could work if browsers supported them. With this extension, if you try to visit a website blocked by AdGuard DNS, it will read the information sent via SDE and display a nice-looking explanation page. Much easier to understand than the examples above, right?

Explanation page

You can install the extension from the Chrome Web Store or from GitHub.

If you want to see what it looks like at the DNS level, you can use the dig command and look for EDE in the output.

% dig @94.140.14.14 'ad.doubleclick.net' A IN +ednsopt=15:0000

...

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; EDE: 17 (Filtered): ({"j":"Filtered by AdGuard DNS","o":"AdGuard DNS","c":["mailto:support@adguard-dns.io"]})
;; QUESTION SECTION:
;ad.doubleclick.net.		IN	A

...

Other improvements: More personalized experience for users and organizations

Our audience includes individuals setting up DNS for their home as well as large organizations. They have different needs and experiences: some need to connect 10 devices and are fine with manual setup; others need to connect 1,000 devices and prefer automation. To better understand each user’s needs, we’ve added an onboarding survey to gather information about goals and expected number of devices.

Onboarding for dashboard