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