63
edits
Changes
Add basic doc for DoH frontend.
This article and its children describe the various mechanics of Firefox's DNS over HTTPS (DoH) frontend. This includes heuristics, default-provider selection, and automatic steering to network-indicated DoH endpoints. Separate [[Trusted Recursive Resolver|documentation]] exists for the protocol implementation in necko.
== Rollout ==
* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* 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.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
== User-choice ==
* User-choice is respected throughout the frontend code.
* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
== Enterprise Policy ==
* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client. This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.
== Heuristics ==
* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* If all of the heuristics pass, DoH is enabled by setting the pref `doh-rollout.mode=2`.
* If any heuristic fails, DoH is disabled by setting the pref `doh-rollout.mode=0`.
== Default Provider Selection ==
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
== Provider Steering ==
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* Currently, Comcast is the only supported provider.
== Opt-out Popup ==
* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This popup offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The popup is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The popup is implemented as a CFR message, gated behind the relevant prefs.
== Telemetry ==
* Interaction and functional data is collected in the form of two telemetry Events.
* 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.
== Migrations ==
* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* 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.
== Rollout ==
* The DoH frontend is gated behind the pref `doh-rollout.enabled`, which by default does not have a value.
* 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.
* Prefs are set to true via Normandy Rollouts, which allows us to target specific regions and control population size and growth so we can manage risk.
== User-choice ==
* User-choice is respected throughout the frontend code.
* If we detect that the user changed their DoH settings in about:preferences, we permanently turn off our heuristics and other mechanisms. The user-set values are obeyed.
== Enterprise Policy ==
* In order to avoid interfering with enterprise-configured network behaviors, we disable our heuristics and other mechanisms if any policy is active on the client. This is true whether the policy is configured on the local machine or propagated by the network e.g. via Group Policy.
* If a DNSOverHTTPS policy to turn on DoH is in effect, this is respected and heuristics and other mechanisms will be enabled.
== Heuristics ==
* We run various heuristics to determine whether the network is (un)suitable to enable DoH.
* The heuristics are run at startup and upon network changes.
* If all of the heuristics pass, DoH is enabled by setting the pref `doh-rollout.mode=2`.
* If any heuristic fails, DoH is disabled by setting the pref `doh-rollout.mode=0`.
== Default Provider Selection ==
* This feature is controlled by the prefs `doh-rollout.trr-selection.enabled`.
* Before running heuristics for the first time, we attempt to choose one of the available providers as the default for the profile.
* The chosen default is used whenever DoH is enabled, via the pref `doh-rollout.uri`.
* A network-provided endpoint, if detected, will take precedence over the default provider when on that network. (See Provider Steering below)
== Provider Steering ==
* This feature is controlled by the pref `doh-rollout.provider-steering.enabled`.
* Some providers supply their own DoH endpoints which we want to use if indicated.
* This capability is discovered via the CNAME response when looking up the domain `doh.test`.
* Discovery is only attempted if all heuristics are passing on the network.
* A DoH endpoint discovered in this manner takes precedence over the automatically chosen default provider (see Default Provider Selection above).
* Currently, Comcast is the only supported provider.
== Opt-out Popup ==
* When the client is first enrolled in the rollout, we show a doorhanger popup to let the user know that DoH is enabled.
* This popup offers an option to opt-out, which results in permanently disabling heuristics and other mechanisms.
* The popup is shown only if the rollout is "successful" - i.e. the user did not already have custom DoH preferences or active enterprise policy.
* The popup is implemented as a CFR message, gated behind the relevant prefs.
== Telemetry ==
* Interaction and functional data is collected in the form of two telemetry Events.
* 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.
== Migrations ==
* We have several migrations to support users upgrading from older versions of Firefox as well as the rollout when they upgrade to newer versions.
* 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.
