Confirmed users
92
edits
Security/DNS Over HTTPS: Difference between revisions
Minor change clarifying that doh.test must include an A or AAAA record in the response.
(add prefs section) |
(Minor change clarifying that doh.test must include an A or AAAA record in the response.) |
||
| (28 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
This article | This article describes the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. See [[Trusted Recursive Resolver]] for details on TRR implementation in necko. | ||
'''Implementation:''' https://searchfox.org/mozilla-central/source/browser/components/doh | |||
== Flow Diagram == | |||
[[File:DoH Controller Flow Diagram.png|750px|frameless|DoH Frontend Flow Diagram]] | |||
== Rollout == | == Rollout == | ||
| Line 6: | Line 12: | ||
* The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true. | * The pref `doh-rollout.enabled`, serves as a blanket gate. Every mechanism described below depends on this pref being set to true. | ||
* Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant. | * Individual mechanisms may be additionally gated behind their own prefs. This is indicated where relevant. | ||
See also: | |||
# https://bugzilla.mozilla.org/show_bug.cgi?id=1571543 | |||
== Heuristics == | == Heuristics == | ||
| Line 13: | Line 21: | ||
* The heuristics are run at startup and upon network changes. | * The heuristics are run at startup and upon network changes. | ||
* DoH is enabled on the network if all heuristics pass, and disabled otherwise. | * DoH is enabled on the network if all heuristics pass, and disabled otherwise. | ||
* | * Main article: [[Security/DNS Over HTTPS/Heuristics]]. | ||
== Respecting User-choice == | == Respecting User-choice == | ||
| Line 32: | Line 40: | ||
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below) | * A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below) | ||
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`. | * This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`. | ||
* | * Choice of provider is made by using each available provider to do lookup several popular domains as well as random subdomains of `firefox-dns-perf-test.net`. | ||
See also: | |||
# https://searchfox.org/mozilla-central/source/browser/components/doh/TRRPerformance.jsm | |||
==== Dry-Run Mechanism ==== | |||
* Default provider selection is done in two phases: a dry-run followed by committing the result. | |||
* By default, this feature is dry-run-only, and records the result in a pref `doh-rollout.trr-selection.dry-run-result`. | |||
* Committing the result is enabled by another pref `doh-rollout.trr-selection.commit-result`. If this is true, then after the dry-run step, the `dry-run-result` will be copied into `doh-rollout.uri`. | |||
[[File:DoH automatic provider selection flow.png|600px|frameless|DoH automatic provider selection flow]] | |||
== Provider Steering == | == Provider Steering == | ||
| Line 41: | Line 60: | ||
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above). | * A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above). | ||
* A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work. | * A provider (endpoint + expected CNAME for discovery) must be explicitly supported for this mechanism to work. | ||
* Currently, Comcast | * The CNAME record must point to a domain that has an A or AAAA record, otherwise getaddrinfo will return NXDOMAIN. | ||
* Currently, Comcast (US) and Shaw (CA) are our only supported providers. | |||
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`. | * This feature is controlled by the pref `doh-rollout.provider-steering.enabled`. | ||
[[File:DoH provider steering flow.png|700px|frameless|DoH Provider Steering Flow]] | |||
* When the client is first enrolled in the rollout, we show | See also: | ||
* This | # https://datatracker.ietf.org/doc/draft-rescorla-doh-cdisco/ | ||
* The | |||
* The | == Opt-out Infobar == | ||
[[File:DoH_Infobar.png|frameless|DoH Infobar screenshot]] | |||
* When the client is first enrolled in the rollout, we show an infobar popup to let the user know that DoH is available. | |||
* This infobar offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms. | |||
* The infobar is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy. | |||
* The infobar is implemented as a CFR message, gated behind the relevant prefs. | |||
See also: | |||
# https://bugzilla.mozilla.org/show_bug.cgi?id=1643651 | |||
Want to see this in action for yourself? | |||
# On a new profile, navigate to about:config | |||
# Set `doh-rollout.enabled` to true | |||
# Close about:config | |||
# Load/reload any website | |||
You'll need to do this in an environment that doesn't trip our heurisitics, i.e. no Canary and no enterprise config. | |||
== Telemetry == | == Telemetry == | ||
| Line 58: | Line 93: | ||
* A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc. | * A ''state'' event is sent when the DoHController's state changes, e.g. when DoH is enabled or disabled on the network, when a user-choice results in disabling heuristics, when a rollback is detected, etc. | ||
* A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status. | * A ''heuristics'' event is sent whenever we run heuristics, containing the result of each heuristic as its payload, along with the trigger (e.g. startup, network change) and the provider steering status. | ||
See also: | |||
# https://searchfox.org/mozilla-central/rev/1b95a0179507a4dc7d4b0c94c2df420dc1a72885/toolkit/components/telemetry/Events.yaml#2097-2158 | |||
== Migrations == | == Migrations == | ||
| Line 65: | Line 102: | ||
* Two of the migrations work on the format of stored state (local storage and prefs) | * Two of the migrations work on the format of stored state (local storage and prefs) | ||
* During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one. | * During a dry-run-only test of Default Provider Selection, an underlying bug was triggered that caused clients to effectively DDoS NextDNS's endpoint. In the aftermath, a new endpoint was set up and we have a migration to convert occurrences of the old endpoint in stored URI values to the new one. | ||
== Prefs == | == Prefs == | ||
* TODO: | * doh-rollout.enabled - Turns on heuristics. Prerequisite for enabling sub-features. | ||
* doh-rollout.provider-steering.enabled - Turns on automatic provider steering. | |||
* doh-rollout.provider-steering.provider-list - Provider data for automatic steering (name, CNAME for discovery, and DoH endpoint) | |||
* doh-rollout.trr-selection.enabled - Turns on automatic performance-based default-TRR selection. Dry-run by default. | |||
* doh-rollout.trr-selection.commit-result - Commits and persists TRR selection dry-run result. | |||
TODO: other state prefs | |||