xref: /aosp_15_r20/external/cronet/net/docs/adding_doh_providers.md (revision 6777b5387eb2ff775bb5750e3f5d96f37fb7352b)

# Adding/Modifying DoH providers

Chrome performs autoupgrade of Classic DNS resolvers to equivalent same-provider
DoH servers using the mapping encoded in
[`DohProviderEntry::GetList()`](/net/dns/public/doh_provider_entry.cc).

[TOC]

## Requesting provider list changes

Official representatives of a DoH provider can request the addition of or
modifications to the entry for their service. See the
[separate documentation](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw)
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.

## Modifying the DoH provider list

*** note
All modifications to the DoH provider list must be accompanied by a request in
the Chromium bug tracker in the
[DoH component](https://bugs.chromium.org/p/chromium/issues/list?q=component:Internals%3ENetwork%3EDoH),
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.
***

1.  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.
1.  Add or modify the [`DohProviderEntry`](/net/dns/public/doh_provider_entry.h)
    entry in
    [`DohProviderEntry::GetList()`](/net/dns/public/doh_provider_entry.cc).
    *   `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.
    *   `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](https://tools.ietf.org/html/rfc6570)
        and [RFC8484](https://tools.ietf.org/html/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](https://docs.google.com/document/d/128i2YTV2C7T6Gr3I-81zlQ-_Lprnsp24qzy_20Z1Psw/edit#heading=h.l3wtx3cufz78).

        ***promo
        Note that all `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.
1.  Manually test the new addition/modification.
    *** promo
    If running tests on enterprise-maintained machines, DoH may be disabled,
    leading to DoH tests always failing and the "Secure DNS" settings being
    disabled. In such cases, a strategic local-only modification to
    [`StubResolverConfigReader`](/chrome/browser/net/stub_resolver_config_reader.cc)
    may be necessary to bypass the disabling.
    ***

    *   After making any additions or modifications to the provider list, run
        the DoH browser tests:
        ```shell
        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:
        ```shell
        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"

        *** aside
        TODO: Document region settings for other operating systems.
        ***
1.  Send the list modification code review to a reviewer in
    [DNS OWNERS](/net/dns/OWNERS), or if no DNS owners are available, to a
    reviewer in [net OWNERS](/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.
1.  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:
    * Create a launch bug, e.g. the [Cox DoH provider launch
      bug](https://crbug.com/1303146).
    * Create a Finch config to roll out each DoH provider, e.g.
      `DnsOverHttpsCox.gcl`.
        * Ensure that the provider's `DohProviderEntry::feature` is disabled by
          default and is enabled by the Finch config.
        * Before landing the Finch config, make the corresponding changes in
          [fieldtrial_testing_config.json](/testing/variations/fieldtrial_testing_config.json).
        * Once the DoH provider's feature has been launched and the Finch
          experiment has expired, `DohProviderEntry::feature` should be enabled
          by default.

## Dynamic control

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](http://go/finch-killswitch).

*** aside
If a user has selected a provider via the "Secure DNS" settings and that
provider becomes disabled, the UI option will disappear from the dropdown but
selection will convert to a custom text-box entry for the same provider and
continue to be used for that user.
***