2 files changed, 482 insertions, 0 deletions
diff --git a/netwerk/docs/dns/dns-over-https-trr.md b/netwerk/docs/dns/dns-over-https-trr.md
new file mode 100644
index 0000000000..dc48edc967
--- /dev/null
+++ b/netwerk/docs/dns/dns-over-https-trr.md
@@ -0,0 +1,158 @@
+---
+title: DNS over HTTPS (Trusted Recursive Resolver)
+---
+
+## Terminology
+
+**DNS-over-HTTPS (DoH)** allows DNS to be resolved with enhanced
+privacy, secure transfers and comparable performance. The protocol is
+described in [RFC 8484](https://tools.ietf.org/html/rfc8484) .
+
+**Trusted Recursive Resolver (TRR)** is the name of Firefox\'s
+implementation of the protocol and the
+[policy](https://wiki.mozilla.org/Security/DOH-resolver-policy) that
+ensures only privacy-respecting DoH providers are recommended by
+Firefox.
+
+On this page we will use DoH when referring to the protocol, and TRR
+when referring to the implementation.
+
+**Unencrypted DNS (Do53)** is the regular way most programs resolve DNS
+names. This is usually done by the operating system by sending an
+unencrypted packet to the DNS server that normally listens on port 53.
+
+## DoH Rollout
+
+**DoH Rollout** refers to the frontend code that decides whether TRR
+will be enabled automatically for users in the [rollout
+population](https://support.mozilla.org/kb/firefox-dns-over-https#w_about-the-us-rollout-of-dns-over-https).
+
+The functioning of this module is described
+[here](https://wiki.mozilla.org/Security/DNS_Over_HTTPS).
+
+The code lives in
+[browser/components/doh](https://searchfox.org/mozilla-central/source/browser/components/doh).
+
+## Implementation
+
+When enabled TRR may work in two modes, TRR-first (2) and TRR-only (3).
+These are controlled by the **network.trr.mode** or **doh-rollout.mode**
+prefs. The difference is that when a DoH request fails in TRR-first
+mode, we then fallback to **Do53**.
+
+For TRR-first mode, we have a strict-fallback setting which can be
+enabled by setting network.trr.strict\_native\_fallback to true. With
+this, while we will still completely skip TRR for certain requests (like
+captive portal detection, bootstrapping the TRR provider, etc.) we will
+only fall back after a TRR failure to **Do53** for three possible
+reasons:
+1. We detected, via Confirmation, that TRR is currently out of
+service on the network. This could mean the provider is down or blocked.
+2. The address successfully resolved via TRR could not be connected to.
+3. TRR result is NXDOMAIN.
+
+When a DNS resolution doesn't use TRR we will normally preserve that data in the form of a _TRRSkippedReason_. A detailed explanation of each one is available [here](trr-skip-reasons).
+
+In other cases, instead of falling back, we will trigger a fresh
+Confirmation (which will start us on a fresh connection to the provider)
+and retry the lookup with TRR again. We only retry once.
+
+DNS name resolutions are performed in _nsHostResolver::ResolveHost_. If a
+cached response for the request could not be found,
+_nsHostResolver::NameLookup_ will trigger either a DoH or a Do53 request.
+First it checks the effective TRR mode of the request is as requests
+could have a different mode from the global one. If the request may use
+TRR, then we dispatch a request in _nsHostResolver::TrrLookup_. Since we
+usually reolve both IPv4 and IPv6 names, a **TRRQuery** object is
+created to perform and combine both responses.
+
+Once done, _nsHostResolver::CompleteLookup_ is called. If the DoH server
+returned a valid response we use it, otherwise we report a failure in
+TRR-only mode, or try Do53 in TRR-first mode.
+
+**TRRService** controls the global state and settings of the feature.
+Each individual request is performed by the **TRR** class.
+
+Since HTTP channels in Firefox normally work on the main thread, TRR
+uses a special implementation called **TRRServiceChannel** to avoid
+congestion on the main thread.
+
+## Dynamic Blocklist
+
+In order to improve performance TRR service manages a dynamic blocklist
+for host names that can\'t be resolved with DoH but work with the native
+resolver. Blocklisted entries will not be retried over DoH for one
+minute (See _network.trr.temp\_blocklist\_duration\_sec_
+pref). When a domain is added to the blocklist, we also check if there
+is an NS record for its parent domain, in which case we add that to the
+blocklist. This feature is controlled by the
+_network.trr.temp\_blocklist_ pref.
+
+## TRR confirmation
+
+TRR requests normally have a 1.5 second timeout. If for some reason we
+do not get a response in that time we fall back to Do53. To avoid this
+delay for all requests when the DoH server is not accessible, we perform
+a confirmation check. If the check fails, we conclude that the server is
+not usable and will use Do53 directly. The confirmation check is retried
+periodically to check if the TRR connection is functional again.
+
+The confirmation state has one of the following values:
+
+-   CONFIRM\_OFF: TRR is turned off, so the service is not active.
+-   CONFIRM\_TRING\_OK: TRR in on, but we are not sure yet if the
+        DoH server is accessible. We optimistically try to resolve via
+        DoH and fall back to Do53 after 1.5 seconds. While in this state
+        the TRRService will be performing NS record requests to the DoH
+        server as a connectivity check. Depending on a successful
+        response it will either transition to the CONFIRM\_OK or
+        CONFIRM\_FAILED state.
+-   CONFIRM\_OK: TRR is on and we have confirmed that the DoH server
+        is behaving adequately. Will use TRR for all requests (and fall
+        back to Do53 in case of timeout, NXDOMAIN, etc).
+-   CONFIRM\_FAILED: TRR is on, but the DoH server is not
+        accessible. Either we have no network connectivity, or the
+        server is down. We don\'t perform DoH requests in this state
+        because they are sure to fail.
+-   CONFIRM\_TRYING\_FAILED: This is equivalent to CONFIRM\_FAILED,
+        but we periodically enter this state when rechecking if the DoH
+        server is accessible.
+-   CONFIRM\_DISABLED: We are in this state if the browser is in
+        TRR-only mode, or if the confirmation was explicitly disabled
+        via pref.
+
+The state machine for the confirmation is defined in the
+_HandleConfirmationEvent_ method in _TRRService.cpp_
+
+If strict fallback mode is enabled, Confirmation will set a flag to
+refresh our connection to the provider.
+
+## Excluded domains
+
+Some domains will never be resolved via TRR. This includes:
+
+-   domains listed in the **network.trr.builtin-excluded-domains** pref
+(normally domains that are equal or end in *localhost* or *local*)
+-   domains listed in the **network.trr.excluded-domains** pref (chosen by the user)
+-   domains that are subdomains of the network\'s DNS suffix
+(for example if the network has the **lan** suffix, domains such as **computer.lan** will not use TRR)
+-   requests made by Firefox to check for the existence of a captive-portal
+-   requests made by Firefox to check the network\'s IPv6 capabilities
+-   domains listed in _/etc/hosts_
+
+## Steering
+
+
+A small set of TRR providers are only available on certain networks.
+Detection is performed in DoHHeuristics.jsm followed by a call to
+_TRRService::SetDetectedURI_. This causes Firefox to use the
+network specific TRR provider until a network change occurs.
+
+## User choice
+
+The TRR feature is designed to prioritize user choice before user agent
+decisions. That means the user may explicitly disable TRR by setting
+**network.trr.mode** to **5** (TRR-disabled), and that
+_doh-rollout_ will not overwrite user settings. Changes to
+the TRR URL or TRR mode by the user will disable heuristics use the user
+configured settings.
diff --git a/netwerk/docs/dns/trr-skip-reasons.md b/netwerk/docs/dns/trr-skip-reasons.md
new file mode 100644
index 0000000000..dbbb4e3336
--- /dev/null
+++ b/netwerk/docs/dns/trr-skip-reasons.md
@@ -0,0 +1,324 @@
+# TRRSkippedReasons
+
+These values are defined in [TRRSkippedReason.h](https://searchfox.org/mozilla-central/source/netwerk/dns/nsITRRSkipReason.idl) and are recorded on _nsHostRecord_ for each resolution.
+We normally use them for telemetry or to determine the cause of a TRR failure.
+
+
+## TRR_UNSET
+
+Value: 0
+
+This reason is set on _nsHostRecord_ before we attempt to resolve the domain.
+Normally we should not report this value into telemetry - if we do that means there's a bug in the code.
+
+
+## TRR_OK
+
+Value: 1
+
+This reason is set when we got a positive TRR result. That means we used TRR for the DNS resolution, the HTTPS request got a 200 response, the response was properly decoded as a DNS packet and that packet contained relevant answers.
+
+
+## TRR_NO_GSERVICE
+
+Value: 2
+
+This reason is only set if there is no TRR service instance when trying to compute the TRR mode for a request. It indicates a bug in the implementation.
+
+
+## TRR_PARENTAL_CONTROL
+
+Value: 3
+
+This reason is set when we have detected system level parental controls are enabled. In this case we will not be using TRR for any requests.
+
+
+## TRR_OFF_EXPLICIT
+
+Value: 4
+
+This reason is set when DNS over HTTPS has been explicitly disabled by the user (by setting _network.trr.mode_ to _5_). In this case we will not be using TRR for any requests.
+
+
+## TRR_REQ_MODE_DISABLED
+
+Value: 5
+
+The request had the _nsIRequest::TRRMode_ set to _TRR\_DISABLED\_MODE_. That is usually the case for request that should not use TRR, such as the TRRServiceChannel, captive portal and connectivity checks, DoHHeuristics checks, requests originating from PAC scripts, etc.
+
+
+## TRR_MODE_NOT_ENABLED
+
+Value: 6
+
+This reason is set when the TRRService is not enabled. The only way we would end up reporting this to telemetry would be if the TRRService was enabled when the request was dispatched, but by the time it was processed the TRRService was disabled.
+
+
+## TRR_FAILED
+
+Value: 7
+
+The TRR request failed for an unknown reason.
+
+
+## TRR_MODE_UNHANDLED_DEFAULT
+
+Value: 8
+
+This reason is no longer used. This value may be recycled to mean something else in the future.
+
+
+## TRR_MODE_UNHANDLED_DISABLED
+
+Value: 9
+
+This reason is no longer used. This value may be recycled to mean something else in the future.
+
+
+## TRR_DISABLED_FLAG
+
+Value: 10
+
+This reason is used when retrying failed connections, sync DNS resolves on the main thread, or requests coming from webextensions that choose to skip TRR.
+
+
+## TRR_TIMEOUT
+
+Value: 11
+
+The TRR request timed out.
+
+## TRR_CHANNEL_DNS_FAIL
+
+Value: 12
+
+This reason is set when we fail to resolve the name of the DNS over HTTPS server.
+
+
+## TRR_IS_OFFLINE
+
+Value: 13
+
+This reason is recorded when the TRR request fails and the browser is offline (no active interfaces).
+
+
+## TRR_NOT_CONFIRMED
+
+Value: 14
+
+This reason is recorded when the TRR Service is not yet confirmed to work. Confirmation is only enabled when _Do53_ fallback is enabled.
+
+
+## TRR_DID_NOT_MAKE_QUERY
+
+Value: 15
+
+This reason is sent when _TrrLookup_ exited without doing a TRR query. It may be set during shutdown, or may indicate an implementation bug.
+
+
+## TRR_UNKNOWN_CHANNEL_FAILURE
+
+Value: 16
+
+The TRR request failed with an unknown channel failure reason.
+
+
+## TRR_HOST_BLOCKED_TEMPORARY
+
+Value: 17
+
+The reason is recorded when the host is temporarily blocked. This happens when a previous attempt to resolve it with TRR failed, but fallback to _Do53_ succeeded.
+
+
+## TRR_SEND_FAILED
+
+Value: 18
+
+The call to TRR::SendHTTPRequest failed.
+
+
+## TRR_NET_RESET
+
+Value: 19
+
+The request failed because the connection to the TRR server was reset.
+
+
+## TRR_NET_TIMEOUT
+
+Value: 20
+
+The request failed because the connection to the TRR server timed out.
+
+
+## TRR_NET_REFUSED
+
+Value: 21
+
+The request failed because the connection to the TRR server was refused.
+
+
+## TRR_NET_INTERRUPT
+
+Value: 22
+
+The request failed because the connection to the TRR server was interrupted.
+
+
+## TRR_NET_INADEQ_SEQURITY
+
+Value: 23
+
+The request failed because the connection to the TRR server used an invalid TLS configuration.
+
+
+## TRR_NO_ANSWERS
+
+Value: 24
+
+The TRR request succeeded but the encoded DNS packet contained no answers.
+
+
+## TRR_DECODE_FAILED
+
+Value: 25
+
+The TRR request succeeded but decoding the DNS packet failed.
+
+
+## TRR_EXCLUDED
+
+Value: 26
+
+This reason is set when the domain being resolved is excluded from TRR, either via the _network.trr.excluded-domains_ pref or because it was covered by the DNS Suffix of the user's network.
+
+
+## TRR_SERVER_RESPONSE_ERR
+
+Value: 27
+
+The server responded with non-200 code.
+
+
+## TRR_RCODE_FAIL
+
+Value: 28
+
+The decoded DNS packet contains an rcode that is different from NOERROR.
+
+
+## TRR_NO_CONNECTIVITY
+
+Value: 29
+
+This reason is set when the browser has no connectivity.
+
+
+## TRR_NXDOMAIN
+
+Value: 30
+
+This reason is set when the DNS response contains NXDOMAIN rcode (0x03).
+
+
+## TRR_REQ_CANCELLED
+
+Value: 31
+
+This reason is set when the request was cancelled prior to completion.
+
+## ODOH_KEY_NOT_USABLE
+
+Value: 32
+
+This reason is set when we don't have a valid ODoHConfig to use.
+
+## ODOH_UPDATE_KEY_FAILED
+
+Value: 33
+
+This reason is set when we failed to update the ODoHConfigs.
+
+## ODOH_KEY_NOT_AVAILABLE
+
+Value: 34
+
+This reason is set when ODoH requests timeout because of no key.
+
+## ODOH_ENCRYPTION_FAILED
+
+Value: 35
+
+This reason is set when we failed to encrypt DNS packets.
+
+## ODOH_DECRYPTION_FAILED
+
+Value: 36
+
+This reason is set when we failed to decrypt DNS packets.
+
+## TRR_HEURISTIC_TRIPPED_GOOGLE_SAFESEARCH
+
+Value: 37
+
+This reason is set when the google safesearch heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_YOUTUBE_SAFESEARCH
+
+Value: 38
+
+This reason is set when the youtube safesearch heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_ZSCALER_CANARY
+
+Value: 39
+
+This reason is set when the zscaler canary heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_CANARY
+
+Value: 40
+
+This reason is set when the global canary heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_MODIFIED_ROOTS
+
+Value: 41
+
+This reason is set when the modified roots (enterprise_roots cert pref) heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_PARENTAL_CONTROLS
+
+Value: 42
+
+This reason is set when parental controls are detected.
+
+## TRR_HEURISTIC_TRIPPED_THIRD_PARTY_ROOTS
+
+Value: 43
+
+This reason is set when the third party roots heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_ENTERPRISE_POLICY
+
+Value: 44
+
+This reason is set when enterprise policy heuristic was tripped.
+
+## TRR_HEURISTIC_TRIPPED_VPN
+
+Value: 45
+
+This reason is set when the heuristic was tripped by a vpn being detected.
+
+## TRR_HEURISTIC_TRIPPED_PROXY
+
+Value: 46
+
+This reason is set when the heuristic was tripped by a proxy being detected.
+
+## TRR_HEURISTIC_TRIPPED_NRPT
+
+Value: 47
+
+This reason is set when the heuristic was tripped by a NRPT being detected.