netwerk/docs/dns/dns-over-https-trr.md

   1 ---
   2 title: DNS over HTTPS (Trusted Recursive Resolver)
   3 ---
   4
   5 ## Terminology
   6
   7 **DNS-over-HTTPS (DoH)** allows DNS to be resolved with enhanced
   8 privacy, secure transfers and comparable performance. The protocol is
   9 described in [RFC 8484](https://tools.ietf.org/html/rfc8484) .
  10
  11 **Trusted Recursive Resolver (TRR)** is the name of Firefox\'s
  12 implementation of the protocol and the
  13 [policy](https://wiki.mozilla.org/Security/DOH-resolver-policy) that
  14 ensures only privacy-respecting DoH providers are recommended by
  15 Firefox.
  16
  17 On this page we will use DoH when referring to the protocol, and TRR
  18 when referring to the implementation.
  19
  20 **Unencrypted DNS (Do53)** is the regular way most programs resolve DNS
  21 names. This is usually done by the operating system by sending an
  22 unencrypted packet to the DNS server that normally listens on port 53.
  23
  24 ## DoH Rollout
  25
  26 **DoH Rollout** refers to the frontend code that decides whether TRR
  27 will be enabled automatically for users in the [rollout
  28 population](https://support.mozilla.org/kb/firefox-dns-over-https#w_about-the-us-rollout-of-dns-over-https).
  29
  30 The functioning of this module is described
  31 [here](https://wiki.mozilla.org/Security/DNS_Over_HTTPS).
  32
  33 The code lives in
  34 [browser/components/doh](https://searchfox.org/mozilla-central/source/browser/components/doh).
  35
  36 ## Implementation
  37
  38 When enabled TRR may work in two modes, TRR-first (2) and TRR-only (3).
  39 These are controlled by the **network.trr.mode** or **doh-rollout.mode**
  40 prefs. The difference is that when a DoH request fails in TRR-first
  41 mode, we then fallback to **Do53**.
  42
  43 For TRR-first mode, we have a strict-fallback setting which can be
  44 enabled by setting network.trr.strict\_native\_fallback to true. With
  45 this, while we will still completely skip TRR for certain requests (like
  46 captive portal detection, bootstrapping the TRR provider, etc.) we will
  47 only fall back after a TRR failure to **Do53** for three possible
  48 reasons:
  49 1. We detected, via Confirmation, that TRR is currently out of
  50 service on the network. This could mean the provider is down or blocked.
  51 2. The address successfully resolved via TRR could not be connected to.
  52 3. TRR result is NXDOMAIN.
  53
  54 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).
  55
  56 In other cases, instead of falling back, we will trigger a fresh
  57 Confirmation (which will start us on a fresh connection to the provider)
  58 and retry the lookup with TRR again. We only retry once.
  59
  60 DNS name resolutions are performed in _nsHostResolver::ResolveHost_. If a
  61 cached response for the request could not be found,
  62 _nsHostResolver::NameLookup_ will trigger either a DoH or a Do53 request.
  63 First it checks the effective TRR mode of the request is as requests
  64 could have a different mode from the global one. If the request may use
  65 TRR, then we dispatch a request in _nsHostResolver::TrrLookup_. Since we
  66 usually reolve both IPv4 and IPv6 names, a **TRRQuery** object is
  67 created to perform and combine both responses.
  68
  69 Once done, _nsHostResolver::CompleteLookup_ is called. If the DoH server
  70 returned a valid response we use it, otherwise we report a failure in
  71 TRR-only mode, or try Do53 in TRR-first mode.
  72
  73 **TRRService** controls the global state and settings of the feature.
  74 Each individual request is performed by the **TRR** class.
  75
  76 Since HTTP channels in Firefox normally work on the main thread, TRR
  77 uses a special implementation called **TRRServiceChannel** to avoid
  78 congestion on the main thread.
  79
  80 ## Dynamic Blocklist
  81
  82 In order to improve performance TRR service manages a dynamic blocklist
  83 for host names that can\'t be resolved with DoH but work with the native
  84 resolver. Blocklisted entries will not be retried over DoH for one
  85 minute (See _network.trr.temp\_blocklist\_duration\_sec_
  86 pref). When a domain is added to the blocklist, we also check if there
  87 is an NS record for its parent domain, in which case we add that to the
  88 blocklist. This feature is controlled by the
  89 _network.trr.temp\_blocklist_ pref.
  90
  91 ## TRR confirmation
  92
  93 TRR requests normally have a 1.5 second timeout. If for some reason we
  94 do not get a response in that time we fall back to Do53. To avoid this
  95 delay for all requests when the DoH server is not accessible, we perform
  96 a confirmation check. If the check fails, we conclude that the server is
  97 not usable and will use Do53 directly. The confirmation check is retried
  98 periodically to check if the TRR connection is functional again.
  99
 100 The confirmation state has one of the following values:
 101
 102 -   CONFIRM\_OFF: TRR is turned off, so the service is not active.
 103 -   CONFIRM\_TRING\_OK: TRR in on, but we are not sure yet if the
 104         DoH server is accessible. We optimistically try to resolve via
 105         DoH and fall back to Do53 after 1.5 seconds. While in this state
 106         the TRRService will be performing NS record requests to the DoH
 107         server as a connectivity check. Depending on a successful
 108         response it will either transition to the CONFIRM\_OK or
 109         CONFIRM\_FAILED state.
 110 -   CONFIRM\_OK: TRR is on and we have confirmed that the DoH server
 111         is behaving adequately. Will use TRR for all requests (and fall
 112         back to Do53 in case of timeout, NXDOMAIN, etc).
 113 -   CONFIRM\_FAILED: TRR is on, but the DoH server is not
 114         accessible. Either we have no network connectivity, or the
 115         server is down. We don\'t perform DoH requests in this state
 116         because they are sure to fail.
 117 -   CONFIRM\_TRYING\_FAILED: This is equivalent to CONFIRM\_FAILED,
 118         but we periodically enter this state when rechecking if the DoH
 119         server is accessible.
 120 -   CONFIRM\_DISABLED: We are in this state if the browser is in
 121         TRR-only mode, or if the confirmation was explicitly disabled
 122         via pref.
 123
 124 The state machine for the confirmation is defined in the
 125 _HandleConfirmationEvent_ method in _TRRService.cpp_
 126
 127 If strict fallback mode is enabled, Confirmation will set a flag to
 128 refresh our connection to the provider.
 129
 130 ## Excluded domains
 131
 132 Some domains will never be resolved via TRR. This includes:
 133
 134 -   domains listed in the **network.trr.builtin-excluded-domains** pref
 135 (normally domains that are equal or end in *localhost* or *local*)
 136 -   domains listed in the **network.trr.excluded-domains** pref (chosen by the user)
 137 -   domains that are subdomains of the network\'s DNS suffix
 138 (for example if the network has the **lan** suffix, domains such as **computer.lan** will not use TRR)
 139 -   requests made by Firefox to check for the existence of a captive-portal
 140 -   requests made by Firefox to check the network\'s IPv6 capabilities
 141 -   domains listed in _/etc/hosts_
 142
 143 ## Steering
 144
 145
 146 A small set of TRR providers are only available on certain networks.
 147 Detection is performed in DoHHeuristics.jsm followed by a call to
 148 _TRRService::SetDetectedURI_. This causes Firefox to use the
 149 network specific TRR provider until a network change occurs.
 150
 151 ## User choice
 152
 153 The TRR feature is designed to prioritize user choice before user agent
 154 decisions. That means the user may explicitly disable TRR by setting
 155 **network.trr.mode** to **5** (TRR-disabled), and that
 156 _doh-rollout_ will not overwrite user settings. Changes to
 157 the TRR URL or TRR mode by the user will disable heuristics use the user
 158 configured settings.