net/docs/adding_doh_providers.md

   1 # Adding/Modifying DoH providers
   2
   3 Chrome performs autoupgrade of Classic DNS resolvers to equivalent same-provider
   4 DoH servers using the mapping encoded in
   5 [`DohProviderEntry::GetList()`](/net/dns/public/doh_provider_entry.cc).
   6
   7 [TOC]
   8
   9 ## Requesting provider list changes
  10
  11 Official representatives of a DoH provider can request the addition of or
  12 modifications to the entry for their service. See the
  13 [separate documentation](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw)
  14 for the criteria and process.
  15
  16 After following the process, if approved, the addition or modification will be
  17 made by a member of the Chromium team.
  18
  19 ## Modifying the DoH provider list
  20
  21 *** note
  22 All modifications to the DoH provider list must be accompanied by a request in
  23 the Chromium bug tracker in the
  24 [DoH component](https://bugs.chromium.org/p/chromium/issues/list?q=component:Internals%3ENetwork%3EDoH),
  25 and that request must be approved by the Chrome team.
  26
  27 It is generally expected that the actual code change will be performed by the
  28 Chrome team on approval of the request.
  29 ***
  30
  31 1.  Ensure the request bug has been approved with a comment from a member of the
  32     Chrome team indicating the approval in the bug. Confirm whether the approved
  33     request is for an autoupgrade mapping, inclusion in the Chrome "Secure DNS"
  34     settings UI, or both.
  35
  36     It is not necessary for the author or reviewer of the CL modifying the
  37     provider list to verify any aspects of the provider criteria, including
  38     ownership of hostnames. That is the responsibility of the Chrome team member
  39     who approved the request bug.
  40 1.  Add or modify the [`DohProviderEntry`](/net/dns/public/doh_provider_entry.h)
  41     entry in
  42     [`DohProviderEntry::GetList()`](/net/dns/public/doh_provider_entry.cc).
  43     *   `provider` is a unique string label used to identify the specific entry.
  44         It may be used for provider-specific metrics data sent to Google or for
  45         [`FeatureParam`](/base/metrics/field_trial_params.h) support via
  46         [`kDnsOverHttpsUpgradeDisabledProvidersParam`](/services/network/public/cpp/features.h)
  47         allowing specific providers to be dynamically disabled. The `provider`
  48         string should be cammelcase, and for cases where a single organization
  49         runs multiple servers/varieties, the overall organization name should go
  50         before the variety-specific name. For example, if ExampleOrg has both
  51         filtered and unfiltered servers, they may have two provider list entries
  52         with the `provider` strings "ExampleOrgFiltered" and
  53         "ExampleOrgUnfiltered".
  54     *   `provider_id_for_histogram` is a
  55         [`DohProviderIdForHistogram`](/net/dns/public/doh_provider_entry.h) enum
  56         value used for histograms data regarding UI interaction. It is only
  57         needed for providers that will be listed in the "Secure DNS" settings.
  58     *   `ip_addresses` is the list of Classic DNS server IP addresses that are
  59         eligible for upgrade to the provider\'s DoH server. The addresses do not
  60         need to be unique within the overall provider list. If multiple DoH
  61         provider entries contain the same `ip_addresses` entry, the DoH servers
  62         for all containing provider entries could become available for use if
  63         Chrome detects that IP address configured. `ip_addresses` may also be
  64         empty if a provider is only available in "Secure DNS" settings and not
  65         for autoupgrade.
  66     *   `dns_over_tls_hostnames` is used for autoupgrade from DoT to DoH. May
  67         be used on platforms where Chrome can recognize configured DoT servers.
  68         Similar to `ip_addresses` in that it may be empty or non-unique. Note
  69         that addition/modification requests in the bug tracker often forget to
  70         mention DoT hostnames, so be sure to ask about it if you suspect a DoH
  71         provider may have an equivalent DoT endpoint.
  72     *   `dns_over_https_template` is the URI template of the DoH server. It is
  73         formatted according to [RFC6570](https://tools.ietf.org/html/rfc6570)
  74         and [RFC8484](https://tools.ietf.org/html/rfc8484). If the template
  75         contains a single `dns` variable, Chrome will perform GET requests, and
  76         if the template contains no variables, Chrome will perform POST
  77         requests. Confirm this matches with the provider's GET/POST preference
  78         in the bug tracker request.
  79     *   `ui_name` is the name that will be displayed to users in the "Secure
  80         DNS" settings. It is only needed for providers that will be listed in
  81         the settings. Confirm that the name conforms to the rules in the
  82         [criteria document](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw/edit#heading=h.l3wtx3cufz78).
  83
  84         ***promo
  85         Note that all `ui_name` values are currently ASCII-only strings. While
  86         non-ASCII names make sense, especially for region-specific providers,
  87         and there is no known issue with using such names, support has not been
  88         thoroughly tested. If adding a non-ASCII name, take extra care to test
  89         that it displays correctly in settings UIs for all platforms.
  90         ***
  91     *   `privacy_policy` is a URL to the privacy policy page for the provider.
  92         It is only needed for providers that will be listed in the settings.
  93     *   `display_globally` sets whether or not a provider will appear in the
  94         "Secure DNS" settings globally for all users. This flag is only expected
  95         to be set for a small number of providers.
  96     *   `display_countries` sets any specific countries in which the provider
  97         should appear in "Secure DNS" settings. Should be empty if
  98         `display_globally` is set. Format is the two-letter ISO 3166-1 country
  99         codes. The provider will be displayed to users when the OS region
 100         settings consider the OS to be in one of the given countries.
 101     *   `logging_level` should be set to `kExtra` for any entry for which
 102         logging/monitoring/etc is especially important. This should be the case
 103         only for the couple most-used providers in the list, newly-entered
 104         providers with some risk of issues, or providers with a history of
 105         issues requiring that provider to be disabled for auto upgrade.
 106 1.  Update histogram entries as necessary.
 107     *   If new providers were added, new `provider` strings must be added to the
 108         [`DohProviderId`](/tools/metrics/histograms/metadata/histogram_suffixes_list.xml)
 109         histogram suffix.
 110     *   If new enum values were added for `provider_id_for_histogram`, the value
 111         must also be added to the
 112         [`DohProviderId`](/tools/metrics/histograms/enums.xml) histogram enum.
 113 1.  Manually test the new addition/modification.
 114     *** promo
 115     If running tests on enterprise-maintained machines, DoH may be disabled,
 116     leading to DoH tests always failing and the "Secure DNS" settings being
 117     disabled. In such cases, a strategic local-only modification to
 118     [`StubResolverConfigReader`](/chrome/browser/net/stub_resolver_config_reader.cc)
 119     may be necessary to bypass the disabling.
 120     ***
 121
 122     *   After making any additions or modifications to the provider list, run
 123         the DoH browser tests:
 124         ```shell
 125         browser_tests.exe --run-manual \
 126         --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.*
 127         ```
 128         Investigate any failures, especially concerning the modified
 129         provider(s).
 130
 131         For new providers, repeat the test 25-100 times (engineer judgement on
 132         how much scrutiny is necessary) for the specific provider to ensure the
 133         provider is reliable:
 134         ```shell
 135         browser_tests.exe --run-manual \
 136         --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.MANUAL_ExternalDohServers/PROVIDER_ID_HERE \
 137         --gtest_repeat=100
 138         ```
 139
 140     *   If adding/modifying a provider intended for display in "Secure DNS"
 141         settings, load up the settings page and select/deselect the provider
 142         followed by making some simple test requests to ensure it functions
 143         correctly.
 144
 145         If the provider is only intended to be displayed in specific countries,
 146         test the settings inside and outside those countries by modifying the OS
 147         region settings and ensuring the entry only displays for the correct
 148         regions. On Windows 10, this setting is found under
 149         "Time & Language" > "Region" > "Country or region"
 150
 151         *** aside
 152         TODO: Document region settings for other operating systems.
 153         ***
 154 1.  Send the list modification code review to a reviewer in
 155     [DNS OWNERS](/net/dns/OWNERS), or if no DNS owners are available, to a
 156     reviewer in [net OWNERS](/net/OWNERS). The reviewer should confirm that the
 157     process defined in this document has been followed, especially that the bug
 158     tracker request has been properly approved.
 159 1.  If a provider must be intially disabled or partially disabled, e.g. because
 160     a provider with significant usage has requested a gradual controlled
 161     rollout, a Googler must modify the `DnsOverHttps.gcl` experiment config.
 162
 163 ## Dynamic control
 164
 165 Googlers may modify the `DnsOverHttps.gcl` experiment config to dynamically
 166 control Chrome DoH via Feature parameters. This support currently allows
 167 disabling or partially disabling individual providers.
 168
 169 *** aside
 170 If a user has selected a provider via the "Secure DNS" settings and that
 171 provider becomes disabled, the UI option will disapear from the dropdown but
 172 selection will convert to a custom text-box entry for the same provider and
 173 continue to be used for that user.
 174 ***