From ade510476e5fb9598507b99878ae33438fe6c4dc Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:10:57 +0300 Subject: [PATCH 01/10] Create an article about SDE --- docs/public-dns/structured-dns-errors.md | 57 ++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/public-dns/structured-dns-errors.md diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md new file mode 100644 index 000000000..6fef26145 --- /dev/null +++ b/docs/public-dns/structured-dns-errors.md @@ -0,0 +1,57 @@ +--- +title: Structured DNS Errors (SDE) +sidebar_position: 2 +--- + +With the release of AdGuard DNS v2.10, AdGuard has become the first public DNS resolver to implement support for [*Structured DNS Errors* (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/), an update to [RFC 8914](https://datatracker.ietf.org/doc/rfc8914/). This feature allows DNS servers to provide detailed information about blocked websites directly in the DNS response, rather than relying on generic browser messages. In this article, we'll explain what *Structured DNS Errors* are and how they work. + +## What Structured DNS Errors are + +When a request to an advertising or tracking domain is blocked, the user may see empty spaces on a website or may not even notice that DNS filtering occurred. However, if an entire website is blocked at the DNS level, the user will be completely unable to access the page. When trying to access a blocked website, the user may see a generic "This site can't be reached" error displayed by the browser. + +!["This site can't be reached" error](https://cdn.adtidy.org/content/blog/dns/dns_error.png) + +Such errors don't explain what happened and why. This leaves users confused about why a website is inaccessible, often leading them to assume that their Internet connection or DNS resolver is broken. + +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. + +![Certificate error](https://cdn.adtidy.org/content/blog/dns/certificate_error.png) + +There’s a simpler solution: [Structured DNS Errors (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/). The concept of SDE builds on the foundation of [*Extended DNS Errors* (RFC 8914)](https://datatracker.ietf.org/doc/rfc8914/), which introduced the ability to include additional error information in DNS responses. Structured DNS Errors take this a step further by using [I-JSON](https://www.rfc-editor.org/rfc/rfc7493) (a restricted profile of JSON) to format the information in a way that browsers and client applications can easily parse. + +The SDE data is included in the `EXTRA-TEXT` field of the DNS response. It contains: + +- `j` (justification): Reason for blocking +- `c` (contact): Contact information for inquiries if the page was blocked by mistake +- `o` (organization): Organization responsible for DNS filtering in this case (optional) +- `s` (suberror): The suberror code for this particular DNS filtering (optional) + +Such a system enhances transparency between DNS services and users. + +### What is required to implement Structured DNS Errors + +Although AdGuard DNS has implemented support for Structured DNS Errors, browsers currently do not natively support parsing and displaying SDE data. For users to see detailed explanations in their browsers when a website is blocked, browser developers need to adopt and support the SDE draft specification. + +### AdGuard DNS demo extension for SDE + +To showcase how Structured DNS Errors work, AdGuard DNS has developed a demo browser extension that shows how *Structured DNS Errors* could work if browsers supported them. If you try to visit a website blocked by AdGuard DNS with this extension enabled, it will display a detailed explanation page with the information provided via SDE, such as the reason for blocking, contact details, and organization responsible. + +![Explanation page](https://cdn.adtidy.org/blog/new/jlkdbaccess_blocked.png) + +You can install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/oeinmjfnchfhaabhchfjkbdpmgeageen) or from [GitHub](https://github.com/AdguardTeam/dns-sde-extension/). + +If you want to see how it looks like on 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 + +... +``` From d484055919b83a79410ea945c25a7a2ae6b47966 Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:17:04 +0300 Subject: [PATCH 02/10] Fix fenced code block --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 6fef26145..9daa771df 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -42,7 +42,7 @@ You can install the extension from the [Chrome Web Store](https://chromewebstore If you want to see how it looks like on the DNS level, you can use the `dig` command and look for `EDE` in the output. -``` +```text % dig @94.140.14.14 'ad.doubleclick.net' A IN +ednsopt=15:0000 ... From 816971f7591038f21f2b38807a6e611626ce279e Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:20:27 +0300 Subject: [PATCH 03/10] Fix hard tabs --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 9daa771df..92d072e17 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -51,7 +51,7 @@ If you want to see how it looks like on the DNS level, you can use the `dig` com ; 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 +;ad.doubleclick.net. IN A ... ``` From aa6a197c8716130a31f61c83e3e93bb3d6ad6e5a Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:36:10 +0300 Subject: [PATCH 04/10] Fix sidebar position --- docs/public-dns/solving-problems/_category_.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/public-dns/solving-problems/_category_.json b/docs/public-dns/solving-problems/_category_.json index f1da209a6..442c2178e 100644 --- a/docs/public-dns/solving-problems/_category_.json +++ b/docs/public-dns/solving-problems/_category_.json @@ -1,6 +1,6 @@ { - "position": 1, + "position": 3, "label": "Solving problems", "collapsible": true, "collapsed": true -} \ No newline at end of file +} From be437a3942454f23a489d3fe11e5d4d47289d732 Mon Sep 17 00:00:00 2001 From: Sofia Orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 12:49:44 +0200 Subject: [PATCH 05/10] Update docs/public-dns/structured-dns-errors.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 92d072e17..0220d6120 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -7,7 +7,7 @@ With the release of AdGuard DNS v2.10, AdGuard has become the first public DNS r ## What Structured DNS Errors are -When a request to an advertising or tracking domain is blocked, the user may see empty spaces on a website or may not even notice that DNS filtering occurred. However, if an entire website is blocked at the DNS level, the user will be completely unable to access the page. When trying to access a blocked website, the user may see a generic "This site can't be reached" error displayed by the browser. +When a request to an advertising or tracking domain is blocked, the user may see blank spaces on a website or may not even notice that DNS filtering has occurred. However, if an entire website is blocked at the DNS level, the user will be completely unable to access the page. When trying to access a blocked website, the user may see a generic "This site can't be reached" error displayed by the browser. !["This site can't be reached" error](https://cdn.adtidy.org/content/blog/dns/dns_error.png) From beb040ec13b2e1a28f1e6c308ef8c84269ea85f5 Mon Sep 17 00:00:00 2001 From: Sofia Orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 12:50:11 +0200 Subject: [PATCH 06/10] Update docs/public-dns/structured-dns-errors.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 0220d6120..ee5a17f7f 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -34,7 +34,7 @@ Although AdGuard DNS has implemented support for Structured DNS Errors, browsers ### AdGuard DNS demo extension for SDE -To showcase how Structured DNS Errors work, AdGuard DNS has developed a demo browser extension that shows how *Structured DNS Errors* could work if browsers supported them. If you try to visit a website blocked by AdGuard DNS with this extension enabled, it will display a detailed explanation page with the information provided via SDE, such as the reason for blocking, contact details, and organization responsible. +To showcase how Structured DNS Errors work, AdGuard DNS has developed a demo browser extension that shows how *Structured DNS Errors* could work if browsers supported them. If you try to visit a website blocked by AdGuard DNS with this extension enabled, you will see a detailed explanation page with the information provided via SDE, such as the reason for blocking, contact details, and the organization responsible. ![Explanation page](https://cdn.adtidy.org/blog/new/jlkdbaccess_blocked.png) From a78c6bb983e7cc748fd600c27cd59113706201c7 Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:53:14 +0300 Subject: [PATCH 07/10] Update structured-dns-errors.md --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 92d072e17..b2be7cf3c 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -17,7 +17,7 @@ To clarify this, DNS servers could redirect users to their own page with an expl ![Certificate error](https://cdn.adtidy.org/content/blog/dns/certificate_error.png) -There’s a simpler solution: [Structured DNS Errors (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/). The concept of SDE builds on the foundation of [*Extended DNS Errors* (RFC 8914)](https://datatracker.ietf.org/doc/rfc8914/), which introduced the ability to include additional error information in DNS responses. Structured DNS Errors take this a step further by using [I-JSON](https://www.rfc-editor.org/rfc/rfc7493) (a restricted profile of JSON) to format the information in a way that browsers and client applications can easily parse. +There’s a simpler solution: [Structured DNS Errors (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/). The concept of SDE builds on the foundation of [*Extended DNS Errors* (RFC 8914)](https://datatracker.ietf.org/doc/rfc8914/), which introduced the ability to include additional error information in DNS responses. The SDE draft takes this a step further by using [I-JSON](https://www.rfc-editor.org/rfc/rfc7493) (a restricted profile of JSON) to format the information in a way that browsers and client applications can easily parse. The SDE data is included in the `EXTRA-TEXT` field of the DNS response. It contains: From e0a754e4623a19a95b737d90eedbb404d6f47419 Mon Sep 17 00:00:00 2001 From: Sofia Orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 12:53:54 +0200 Subject: [PATCH 08/10] Update docs/public-dns/structured-dns-errors.md Co-authored-by: Helen <58733007+el-termikael@users.noreply.github.com> --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index ebe5955ae..297dd2dc4 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -40,7 +40,7 @@ To showcase how Structured DNS Errors work, AdGuard DNS has developed a demo bro You can install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/oeinmjfnchfhaabhchfjkbdpmgeageen) or from [GitHub](https://github.com/AdguardTeam/dns-sde-extension/). -If you want to see how it looks like on the DNS level, you can use the `dig` command and look for `EDE` in the output. +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. ```text % dig @94.140.14.14 'ad.doubleclick.net' A IN +ednsopt=15:0000 From d5d713c9c0fe075c5e377b4caa4bacdf64eca905 Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 14:20:38 +0300 Subject: [PATCH 09/10] Fix image cache issue --- docs/public-dns/structured-dns-errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/public-dns/structured-dns-errors.md b/docs/public-dns/structured-dns-errors.md index 297dd2dc4..4f835902f 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/public-dns/structured-dns-errors.md @@ -15,7 +15,7 @@ Such errors don't explain what happened and why. This leaves users confused abou 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. -![Certificate error](https://cdn.adtidy.org/content/blog/dns/certificate_error.png) +![Certificate error](https://cdn.adtidy.org/content/blog/dns/certificate_error.png?1) There’s a simpler solution: [Structured DNS Errors (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/). The concept of SDE builds on the foundation of [*Extended DNS Errors* (RFC 8914)](https://datatracker.ietf.org/doc/rfc8914/), which introduced the ability to include additional error information in DNS responses. The SDE draft takes this a step further by using [I-JSON](https://www.rfc-editor.org/rfc/rfc7493) (a restricted profile of JSON) to format the information in a way that browsers and client applications can easily parse. From 7aea1312785ead71bd41fd95ddf64019b43e6797 Mon Sep 17 00:00:00 2001 From: ss-orlova <95080242+sonya-orlova@users.noreply.github.com> Date: Thu, 14 Nov 2024 14:44:29 +0300 Subject: [PATCH 10/10] Move article to Miscellaneous --- docs/miscellaneous/acknowledgements.md | 2 +- docs/miscellaneous/create-dns-stamp.md | 6 +++++- docs/{public-dns => miscellaneous}/structured-dns-errors.md | 2 +- docs/miscellaneous/take-screenshot.md | 2 +- docs/miscellaneous/update-kb.md | 2 +- docs/public-dns/solving-problems/_category_.json | 2 +- 6 files changed, 10 insertions(+), 6 deletions(-) rename docs/{public-dns => miscellaneous}/structured-dns-errors.md (99%) diff --git a/docs/miscellaneous/acknowledgements.md b/docs/miscellaneous/acknowledgements.md index 2dc61fc71..dee62d166 100644 --- a/docs/miscellaneous/acknowledgements.md +++ b/docs/miscellaneous/acknowledgements.md @@ -1,6 +1,6 @@ --- title: Credits and Acknowledgements -sidebar_position: 5 +sidebar_position: 3 --- Our dev team would like to thank the developers of the third-party software we use in AdGuard DNS, our great beta testers and other engaged users, whose help in finding and eliminating all the bugs, translating AdGuard DNS, and moderating our communities is priceless. diff --git a/docs/miscellaneous/create-dns-stamp.md b/docs/miscellaneous/create-dns-stamp.md index 31b39e45e..7fde0b29e 100644 --- a/docs/miscellaneous/create-dns-stamp.md +++ b/docs/miscellaneous/create-dns-stamp.md @@ -1,4 +1,8 @@ -# How to create your own DNS stamp for Secure DNS +--- +title: How to create your own DNS stamp for Secure DNS + +sidebar_position: 4 +--- This guide will show you how to create your own DNS stamp for Secure DNS. Secure DNS is a service that enhances your internet security and privacy by encrypting your DNS queries. This prevents your queries from being intercepted or manipulated by malicious actors. diff --git a/docs/public-dns/structured-dns-errors.md b/docs/miscellaneous/structured-dns-errors.md similarity index 99% rename from docs/public-dns/structured-dns-errors.md rename to docs/miscellaneous/structured-dns-errors.md index 4f835902f..0a7836dc4 100644 --- a/docs/public-dns/structured-dns-errors.md +++ b/docs/miscellaneous/structured-dns-errors.md @@ -1,6 +1,6 @@ --- title: Structured DNS Errors (SDE) -sidebar_position: 2 +sidebar_position: 5 --- With the release of AdGuard DNS v2.10, AdGuard has become the first public DNS resolver to implement support for [*Structured DNS Errors* (SDE)](https://datatracker.ietf.org/doc/draft-ietf-dnsop-structured-dns-error/09/), an update to [RFC 8914](https://datatracker.ietf.org/doc/rfc8914/). This feature allows DNS servers to provide detailed information about blocked websites directly in the DNS response, rather than relying on generic browser messages. In this article, we'll explain what *Structured DNS Errors* are and how they work. diff --git a/docs/miscellaneous/take-screenshot.md b/docs/miscellaneous/take-screenshot.md index 529c9cf08..eb7ef1ad4 100644 --- a/docs/miscellaneous/take-screenshot.md +++ b/docs/miscellaneous/take-screenshot.md @@ -1,6 +1,6 @@ --- title: 'How to take a screenshot' -sidebar_position: 4 +sidebar_position: 2 --- Screenshot is a capture of your computer’s or mobile device’s screen, which can be obtained by using standard tools or a special program/app. diff --git a/docs/miscellaneous/update-kb.md b/docs/miscellaneous/update-kb.md index 9f69a301a..43e23a037 100644 --- a/docs/miscellaneous/update-kb.md +++ b/docs/miscellaneous/update-kb.md @@ -1,6 +1,6 @@ --- title: 'Updating the Knowledge Base' -sidebar_position: 3 +sidebar_position: 1 --- The goal of this Knowledge Base is to provide everyone with the most up-to-date information on all kinds of AdGuard DNS-related topics. But things constantly change, and sometimes an article doesn't reflect the current state of things anymore — there are simply not so many of us to keep an eye on every single bit of information and update it accordingly when new versions are released. diff --git a/docs/public-dns/solving-problems/_category_.json b/docs/public-dns/solving-problems/_category_.json index 442c2178e..b9a8de5f0 100644 --- a/docs/public-dns/solving-problems/_category_.json +++ b/docs/public-dns/solving-problems/_category_.json @@ -1,5 +1,5 @@ { - "position": 3, + "position": 2, "label": "Solving problems", "collapsible": true, "collapsed": true