Chrome performs autoupgrade of Classic DNS resolvers to equivalent same-provider DoH servers using the mapping encoded in DohProviderEntry::GetList().
Official representatives of a DoH provider can request the addition of or modifications to the entry for their service. See the separate documentation for the criteria and process.
After following the process, if approved, the addition or modification will be made by a member of the Chromium team.
All modifications to the DoH provider list must be accompanied by a request in the Chromium bug tracker in the DoH component, and that request must be approved by the Chrome team.
It is generally expected that the actual code change will be performed by the Chrome team on approval of the request.
Ensure the request bug has been approved with a comment from a member of the Chrome team indicating the approval in the bug. Confirm whether the approved request is for an autoupgrade mapping, inclusion in the Chrome “Secure DNS” settings UI, or both.
It is not necessary for the author or reviewer of the CL modifying the provider list to verify any aspects of the provider criteria, including ownership of hostnames. That is the responsibility of the Chrome team member who approved the request bug.
Add or modify the DohProviderEntry entry in DohProviderEntry::GetList().
provider is a unique string label used to identify the specific entry. It may be used for provider-specific metrics data sent to Google. The provider string should be camelcase, and for cases where a single organization runs multiple servers/varieties, the overall organization name should go before the variety-specific name. For example, if ExampleOrg has both filtered and unfiltered servers, they may have two provider list entries with the provider strings “ExampleOrgFiltered” and “ExampleOrgUnfiltered”.
feature is used by experiments to control an individual provider. When the feature is disabled, either by default or remotely by an experiment config, the provider is not eligible for autoupgrade and it will not be listed in the “Secure DNS” settings.
provider_id_for_histogram is a DohProviderIdForHistogram enum value used for histograms data regarding UI interaction. It is only needed for providers that will be listed in the “Secure DNS” settings.
ip_addresses is the list of Classic DNS server IP addresses that are eligible for upgrade to the provider's DoH server. The addresses do not need to be unique within the overall provider list. If multiple DoH provider entries contain the same ip_addresses entry, the DoH servers for all containing provider entries could become available for use if Chrome detects that IP address configured. ip_addresses may also be empty if a provider is only available in “Secure DNS” settings and not for autoupgrade.
dns_over_tls_hostnames is used for autoupgrade from DoT to DoH. May be used on platforms where Chrome can recognize configured DoT servers. Similar to ip_addresses in that it may be empty or non-unique. Note that addition/modification requests in the bug tracker often forget to mention DoT hostnames, so be sure to ask about it if you suspect a DoH provider may have an equivalent DoT endpoint.
dns_over_https_template is the URI template of the DoH server. It is formatted according to RFC6570 and RFC8484. If the template contains a single dns variable, Chrome will perform GET requests, and if the template contains no variables, Chrome will perform POST requests. Confirm this matches with the provider's GET/POST preference in the bug tracker request.
ui_name is the name that will be displayed to users in the “Secure DNS” settings. It is only needed for providers that will be listed in the settings. Confirm that the name conforms to the rules in the criteria document.
ui_name values are currently ASCII-only strings. While non-ASCII names make sense, especially for region-specific providers, and there is no known issue with using such names, support has not been thoroughly tested. If adding a non-ASCII name, take extra care to test that it displays correctly in settings UIs for all platforms.privacy_policy is a URL to the privacy policy page for the provider. It is only needed for providers that will be listed in the settings.
display_globally sets whether or not a provider will appear in the “Secure DNS” settings globally for all users. This flag is only expected to be set for a small number of providers.
display_countries sets any specific countries in which the provider should appear in “Secure DNS” settings. Should be empty if display_globally is set. Format is the two-letter ISO 3166-1 country codes. The provider will be displayed to users when the OS region settings consider the OS to be in one of the given countries.
logging_level should be set to kExtra for any entry for which logging/monitoring/etc is especially important. This should be the case only for the couple most-used providers in the list, newly-entered providers with some risk of issues, or providers with a history of issues requiring that provider to be disabled for auto upgrade.
Update histogram entries as necessary.
provider strings must be added to the DohProviderId histogram suffix.provider_id_for_histogram, the value must also be added to the DohProviderId histogram enum.Manually test the new addition/modification.
StubResolverConfigReader may be necessary to bypass the disabling.After making any additions or modifications to the provider list, run the DoH browser tests:
browser_tests.exe --run-manual \ --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.*
Investigate any failures, especially concerning the modified provider(s).
For new providers, repeat the test 25-100 times (exercise judgment on how much scrutiny is necessary) for the specific provider to ensure the provider is reliable:
browser_tests.exe --run-manual \ --gtest_filter= DohBrowserParameterizedTest/DohBrowserTest.MANUAL_ExternalDohServers/PROVIDER_ID_HERE \ --gtest_repeat=100
If adding/modifying a provider intended for display in “Secure DNS” settings, load up the settings page and select/deselect the provider followed by making some simple test requests to ensure it functions correctly.
If the provider is only intended to be displayed in specific countries, test the settings inside and outside those countries by modifying the OS region settings and ensuring the entry only displays for the correct regions. On Windows 10, this setting is found under “Time & Language” > “Region” > “Country or region”
Send the list modification code review to a reviewer in DNS OWNERS, or if no DNS owners are available, to a reviewer in net OWNERS. The reviewer should confirm that the process defined in this document has been followed, especially that the bug tracker request has been properly approved.
If a provider must be initially disabled or partially disabled, e.g. because a provider with significant usage has requested a gradual controlled rollout, a Googler must:
DnsOverHttpsCox.gcl.DohProviderEntry::feature is disabled by default and is enabled by the Finch config.DohProviderEntry::feature should be enabled by default.DoH providers, especially new ones, may have service interruptions or performance degradation to the point that it's necessary to disable their autoupgrade feature.
If the malfunctioning DoH provider is still in the middle of a gradual rollout, Googlers may dynamically disable the provider by modifying its experiment config (DnsOverHttps${ProviderName}.gcl).
Otherwise, if the provider's autoupgrade feature has already been launched, Googlers should create a new “kill switch config” rather than reuse the expired gradual rollout config. Follow the guidance at go/finch-killswitch.