1# Adding/Modifying DoH providers 2 3Chrome performs autoupgrade of Classic DNS resolvers to equivalent same-provider 4DoH 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 11Official representatives of a DoH provider can request the addition of or 12modifications to the entry for their service. See the 13[separate documentation](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw) 14for the criteria and process. 15 16After following the process, if approved, the addition or modification will be 17made by a member of the Chromium team. 18 19## Modifying the DoH provider list 20 21*** note 22All modifications to the DoH provider list must be accompanied by a request in 23the Chromium bug tracker in the 24[DoH component](https://bugs.chromium.org/p/chromium/issues/list?q=component:Internals%3ENetwork%3EDoH), 25and that request must be approved by the Chrome team. 26 27It is generally expected that the actual code change will be performed by the 28Chrome team on approval of the request. 29*** 30 311. 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. 401. 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. The 45 `provider` string should be camelcase, and for cases where a single 46 organization runs multiple servers/varieties, the overall organization 47 name should go before the variety-specific name. For example, if 48 ExampleOrg has both filtered and unfiltered servers, they may have two 49 provider list entries with the `provider` strings "ExampleOrgFiltered" 50 and "ExampleOrgUnfiltered". 51 * `feature` is used by experiments to control an individual provider. When 52 the feature is disabled, either by default or remotely by an experiment 53 config, the provider is not eligible for autoupgrade and it will not be 54 listed in the "Secure DNS" settings. 55 * `provider_id_for_histogram` is a 56 [`DohProviderIdForHistogram`](/net/dns/public/doh_provider_entry.h) enum 57 value used for histograms data regarding UI interaction. It is only 58 needed for providers that will be listed in the "Secure DNS" settings. 59 * `ip_addresses` is the list of Classic DNS server IP addresses that are 60 eligible for upgrade to the provider\'s DoH server. The addresses do not 61 need to be unique within the overall provider list. If multiple DoH 62 provider entries contain the same `ip_addresses` entry, the DoH servers 63 for all containing provider entries could become available for use if 64 Chrome detects that IP address configured. `ip_addresses` may also be 65 empty if a provider is only available in "Secure DNS" settings and not 66 for autoupgrade. 67 * `dns_over_tls_hostnames` is used for autoupgrade from DoT to DoH. May 68 be used on platforms where Chrome can recognize configured DoT servers. 69 Similar to `ip_addresses` in that it may be empty or non-unique. Note 70 that addition/modification requests in the bug tracker often forget to 71 mention DoT hostnames, so be sure to ask about it if you suspect a DoH 72 provider may have an equivalent DoT endpoint. 73 * `dns_over_https_template` is the URI template of the DoH server. It is 74 formatted according to [RFC6570](https://tools.ietf.org/html/rfc6570) 75 and [RFC8484](https://tools.ietf.org/html/rfc8484). If the template 76 contains a single `dns` variable, Chrome will perform GET requests, and 77 if the template contains no variables, Chrome will perform POST 78 requests. Confirm this matches with the provider's GET/POST preference 79 in the bug tracker request. 80 * `ui_name` is the name that will be displayed to users in the "Secure 81 DNS" settings. It is only needed for providers that will be listed in 82 the settings. Confirm that the name conforms to the rules in the 83 [criteria document](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw/edit#heading=h.l3wtx3cufz78). 84 85 ***promo 86 Note that all `ui_name` values are currently ASCII-only strings. While 87 non-ASCII names make sense, especially for region-specific providers, 88 and there is no known issue with using such names, support has not been 89 thoroughly tested. If adding a non-ASCII name, take extra care to test 90 that it displays correctly in settings UIs for all platforms. 91 *** 92 * `privacy_policy` is a URL to the privacy policy page for the provider. 93 It is only needed for providers that will be listed in the settings. 94 * `display_globally` sets whether or not a provider will appear in the 95 "Secure DNS" settings globally for all users. This flag is only expected 96 to be set for a small number of providers. 97 * `display_countries` sets any specific countries in which the provider 98 should appear in "Secure DNS" settings. Should be empty if 99 `display_globally` is set. Format is the two-letter ISO 3166-1 country 100 codes. The provider will be displayed to users when the OS region 101 settings consider the OS to be in one of the given countries. 102 * `logging_level` should be set to `kExtra` for any entry for which 103 logging/monitoring/etc is especially important. This should be the case 104 only for the couple most-used providers in the list, newly-entered 105 providers with some risk of issues, or providers with a history of 106 issues requiring that provider to be disabled for auto upgrade. 1071. Update histogram entries as necessary. 108 * If new providers were added, new `provider` strings must be added to the 109 [`DohProviderId`](/tools/metrics/histograms/metadata/histogram_suffixes_list.xml) 110 histogram suffix. 111 * If new enum values were added for `provider_id_for_histogram`, the value 112 must also be added to the 113 [`DohProviderId`](/tools/metrics/histograms/enums.xml) histogram enum. 1141. Manually test the new addition/modification. 115 *** promo 116 If running tests on enterprise-maintained machines, DoH may be disabled, 117 leading to DoH tests always failing and the "Secure DNS" settings being 118 disabled. In such cases, a strategic local-only modification to 119 [`StubResolverConfigReader`](/chrome/browser/net/stub_resolver_config_reader.cc) 120 may be necessary to bypass the disabling. 121 *** 122 123 * After making any additions or modifications to the provider list, run 124 the DoH browser tests: 125 ```shell 126 browser_tests.exe --run-manual \ 127 --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.* 128 ``` 129 Investigate any failures, especially concerning the modified 130 provider(s). 131 132 For new providers, repeat the test 25-100 times (exercise judgment on 133 how much scrutiny is necessary) for the specific provider to ensure the 134 provider is reliable: 135 ```shell 136 browser_tests.exe --run-manual \ 137 --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.MANUAL_ExternalDohServers/PROVIDER_ID_HERE \ 138 --gtest_repeat=100 139 ``` 140 141 * If adding/modifying a provider intended for display in "Secure DNS" 142 settings, load up the settings page and select/deselect the provider 143 followed by making some simple test requests to ensure it functions 144 correctly. 145 146 If the provider is only intended to be displayed in specific countries, 147 test the settings inside and outside those countries by modifying the OS 148 region settings and ensuring the entry only displays for the correct 149 regions. On Windows 10, this setting is found under 150 "Time & Language" > "Region" > "Country or region" 151 152 *** aside 153 TODO: Document region settings for other operating systems. 154 *** 1551. Send the list modification code review to a reviewer in 156 [DNS OWNERS](/net/dns/OWNERS), or if no DNS owners are available, to a 157 reviewer in [net OWNERS](/net/OWNERS). The reviewer should confirm that the 158 process defined in this document has been followed, especially that the bug 159 tracker request has been properly approved. 1601. If a provider must be initially disabled or partially disabled, e.g. because 161 a provider with significant usage has requested a gradual controlled 162 rollout, a Googler must: 163 * Create a launch bug, e.g. the [Cox DoH provider launch 164 bug](https://crbug.com/1303146). 165 * Create a Finch config to roll out each DoH provider, e.g. 166 `DnsOverHttpsCox.gcl`. 167 * Ensure that the provider's `DohProviderEntry::feature` is disabled by 168 default and is enabled by the Finch config. 169 * Before landing the Finch config, make the corresponding changes in 170 [fieldtrial_testing_config.json](/testing/variations/fieldtrial_testing_config.json). 171 * Once the DoH provider's feature has been launched and the Finch 172 experiment has expired, `DohProviderEntry::feature` should be enabled 173 by default. 174 175## Dynamic control 176 177DoH providers, especially new ones, may have service interruptions or 178performance degradation to the point that it's necessary to disable their 179autoupgrade feature. 180 181If the malfunctioning DoH provider is still in the middle of a gradual rollout, 182Googlers may dynamically disable the provider by modifying its experiment config 183(`DnsOverHttps${ProviderName}.gcl`). 184 185Otherwise, if the provider's autoupgrade feature has already been launched, 186Googlers should create a new "kill switch config" rather than reuse the expired 187gradual rollout config. Follow the guidance at 188[go/finch-killswitch](http://go/finch-killswitch). 189 190*** aside 191If a user has selected a provider via the "Secure DNS" settings and that 192provider becomes disabled, the UI option will disappear from the dropdown but 193selection will convert to a custom text-box entry for the same provider and 194continue to be used for that user. 195*** 196