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

   1 DNS over HTTPS (Trusted Recursive Resolver)
   2 ===========================================
   3
   4 Terminology
   5 -----------
   6
   7 **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>`_ .
   8
   9
  10 **Trusted Recursive Resolver (TRR)** is the name of Firefox's implementation
  11 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.
  12
  13 On this page we will use DoH when referring to the protocol, and TRR when referring to the implementation.
  14
  15 **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
  16 that normally listens on port 53.
  17
  18 DoH Rollout
  19 -----------
  20
  21 **DoH Rollout** refers to the frontend code that decides whether TRR will
  22 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>`_.
  23
  24 The functioning of this module is described `here <https://wiki.mozilla.org/Security/DNS_Over_HTTPS>`_.
  25
  26 The code lives in `browser/components/doh <https://searchfox.org/mozilla-central/source/browser/components/doh>`_.
  27
  28 Implementation
  29 --------------
  30
  31 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.
  32 The difference is that when a DoH request fails in TRR-first mode, we then fallback to **Do53**.
  33
  34 For TRR-first mode, we have a strict-fallback setting which can be enabled by setting network.trr.strict_native_fallback to true.
  35 With this, while we will still completely skip TRR for certain requests (like captive portal detection, bootstrapping the TRR provider, etc.)
  36 we will only fall back after a TRR failure to **Do53** for three possible reasons:
  37 1. We detected, via Confirmation, that TRR is currently out of service on the network. This could mean the provider is down or blocked.
  38 2. The address successfully resolved via TRR could not be connected to.
  39 3. TRR result is NXDOMAIN.
  40
  41 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
  42 retry the lookup with TRR again. We only retry once.
  43
  44 DNS name resolutions are performed in nsHostResolver::ResolveHost. If a cached response for the request could not be found, nsHostResolver::NameLookup will trigger either
  45 a DoH or a Do53 request. First it checks the effective TRR mode of the request
  46 is as requests could have a different mode from the global one.
  47 If the request may use TRR, then we dispatch a request in nsHostResolver::TrrLookup.
  48 Since we usually reolve both IPv4 and IPv6 names, a **TRRQuery** object is
  49 created to perform and combine both responses.
  50
  51 Once done, nsHostResolver::CompleteLookup is called. If the DoH server returned a
  52 valid response we use it, otherwise we report a failure in TRR-only mode, or
  53 try Do53 in TRR-first mode.
  54
  55 **TRRService** controls the global state and settings of the feature.
  56 Each individual request is performed by the **TRR** class.
  57
  58 Since HTTP channels in Firefox normally work on the main thread, TRR uses a
  59 special implementation called **TRRServiceChannel** to avoid congestion on the
  60 main thread.
  61
  62 Dynamic Blocklist
  63 -----------------
  64
  65 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).
  66 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.
  67 This feature is controlled by the `network.trr.temp_blocklist` pref.
  68
  69 TRR confirmation
  70 ----------------
  71
  72 TRR requests normally have a 1.5 second timeout. If for some reason we do not
  73 get a response in that time we fall back to Do53. To avoid this delay for all
  74 requests when the DoH server is not accessible, we perform a confirmation check.
  75 If the check fails, we conclude that the server is not usable and will use Do53
  76 directly. The confirmation check is retried periodically to check if the TRR
  77 connection is functional again.
  78
  79 The confirmation state has one of the following values:
  80   - CONFIRM_OFF: TRR is turned off, so the service is not active.
  81   - 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.
  82   - 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).
  83   - 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.
  84   - CONFIRM_TRYING_FAILED: This is equivalent to CONFIRM_FAILED, but we periodically enter this state when rechecking if the DoH server is accessible.
  85   - CONFIRM_DISABLED: We are in this state if the browser is in TRR-only mode, or if the confirmation was explicitly disabled via pref.
  86
  87 The state machine for the confirmation is defined in the `HandleConfirmationEvent` method in `TRRService.cpp`.
  88
  89 If strict fallback mode is enabled, Confirmation will set a flag to refresh our connection to the provider.
  90
  91 Excluded domains
  92 ----------------
  93
  94 Some domains will never be resolved via TRR. This includes:
  95   - domains listed in the **network.trr.builtin-excluded-domains** pref (normally domains that are equal or end in *localhost* or *local*)
  96   - domains listed in the **network.trr.excluded-domains** pref (chosen by the user)
  97   - 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)
  98   - requests made by Firefox to check for the existence of a captive-portal
  99   - requests made by Firefox to check the network's IPv6 capabilities
 100   - domains listed in `/etc/hosts`
 101
 102 Steering
 103 --------
 104
 105 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`.
 106 This causes Firefox to use the network specific TRR provider until a network change occurs.
 107
 108 User choice
 109 -----------
 110
 111 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.
 112 Changes to the TRR URL or TRR mode by the user will disable heuristics use the user configured settings.