services/network/public/mojom/network_service.mojom

// Copyright 2017 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "components/content_settings/core/common/content_settings.mojom";
import "mojo/public/mojom/base/byte_string.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/memory_pressure_level.mojom";
import "mojo/public/mojom/base/proto_wrapper.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/values.mojom";
import "sandbox/policy/mojom/context.mojom";
import "sandbox/policy/mojom/sandbox.mojom";
import "services/network/public/mojom/client_security_state.mojom";
import "services/network/public/mojom/first_party_sets.mojom";
import "services/network/public/mojom/host_resolver.mojom";
import "services/network/public/mojom/http_raw_headers.mojom";
import "services/network/public/mojom/ip_address_space.mojom";
import "services/network/public/mojom/ip_endpoint.mojom";
import "services/network/public/mojom/key_pinning.mojom";
import "services/network/public/mojom/mutable_network_traffic_annotation_tag.mojom";
import "services/network/public/mojom/net_log.mojom";
import "services/network/public/mojom/network_annotation_monitor.mojom";
import "services/network/public/mojom/network_change_manager.mojom";
import "services/network/public/mojom/network_context.mojom";
import "services/network/public/mojom/network_interface.mojom";
import "services/network/public/mojom/network_interface_change_listener.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/network_quality_estimator_manager.mojom";
import "services/network/public/mojom/network_service_test.mojom";
import "services/network/public/mojom/parsed_headers.mojom";
import "services/network/public/mojom/proxy_config.mojom";
import "services/network/public/mojom/schemeful_site.mojom";
import "services/network/public/mojom/source_type.mojom";
import "services/network/public/mojom/system_dns_resolution.mojom";
import "services/network/public/mojom/trust_tokens.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_network_service_observer.mojom";
import "services/network/public/mojom/url_response_head.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

[EnableIf=is_android]
import "mojo/public/mojom/base/application_state.mojom";

[EnableIf=is_ct_supported]
import "services/network/public/mojom/ct_log_info.mojom";

// Values for configuring HTTP authentication that can only be set once.
struct HttpAuthStaticParams {
  // File name the GSSAPI library to load. Only supported on platforms where an
  // external GSSAPI library is necessary for Kerberos/SPNEGO support. See the
  // |use_external_gssapi| variable definition in //net/BUILD.gn for details on
  // platforms where this setting is applicable.
  string gssapi_library_name;
};

// Values for configurating HTTP authentication that can be changed as needed.
struct HttpAuthDynamicParams {
  // List of allowed auth schemes. Unrecognized schemes are ignored.
  array<string>? allowed_schemes;

  // List of origins patterns that are allowed the use of all the HTTP auth
  // schemes recognized and supported by the browser regardless of
  // `allowed_schemes`. The accepted format is documented at
  // http://www.chromium.org/administrators/url-blocklist-filter-format.
  array<string> patterns_allowed_to_use_all_schemes;

  // Comma / semi-colon delimited allowlist of server origins which the network
  // service may send the default credentials for NTLM or Negotiate
  // authentication.
  string server_allowlist;

  // Comma / semi-colon delimited allowlist of server origins for which Kerberos
  // delegation is allowed for NTLM or Negotiate authentication.
  string delegate_allowlist;

  // True if OK-AS-DELEGATE flag from KDC should be used to allow delegation for
  // Negotiate authentication along with delegate_allowlist;
  bool delegate_by_kdc_policy = false;

  // True if canonical hostnames should be resolved when using Negotiate.
  bool negotiate_disable_cname_lookup = false;

  // True if Negotiate SPNs (service principal names) should include ports
  // when the port isn't a standard port (80 or 443).
  bool enable_negotiate_port = false;

  // Whether NTLM V2 is enabled on POSIX platforms. No effect elsewhere.
  bool ntlm_v2_enabled = true;

  // The AccountManager AccountManagerget.AccountsByTypeAndFeatures on Android
  // when using Negotiate authentication.
  string android_negotiate_account_type;

  // Indicates whether the GSSAPI library should be loaded. Only supported on
  // Chrome OS and Linux.
  bool allow_gssapi_library_load = true;

  // True if Basic authentication challenges should be allowed for non-secure
  // HTTP responses.
  bool basic_over_http_enabled = true;
};

// Represents the value of a single environment variable.
struct EnvironmentVariable {
  string name;
  string value;
};

// Parameters needed to initialize the network service.
struct NetworkServiceParams {
  ConnectionType initial_connection_type = CONNECTION_UNKNOWN;
  ConnectionSubtype initial_connection_subtype = SUBTYPE_UNKNOWN;

  // The initial AddressMapOwnerLinux::AddressMap and set of online links for
  // the AddressMapCacheLinux in the network service.
  // TODO(crbug.com/40220507): this should be non-optional once the kill switch
  // is removed.
  [EnableIf=use_network_interface_change_listener]
  InitialAddressMap? initial_address_map;

  // A set of environment variables that should be set in the network
  // service when starting up.
  array<EnvironmentVariable> environment;

  // An URLLoaderFactory can provide its own URLLoaderNetworkServiceObserver
  // but if it does not, this default will be used.
  pending_remote<URLLoaderNetworkServiceObserver> default_observer;

  // A boolean provided by the Browser Process in order to plumb into the
  // First-Party Sets attribute during NetworkService::Initialize().
  bool first_party_sets_enabled;

  // A SystemDnsResolver to provide out-of-process system DNS resolution, in
  // case the system DNS resolver cannot always run sandboxed.
  pending_remote<SystemDnsResolver>? system_dns_resolver;
};

// Configuration settings for SCT Auditing.
[EnableIf=is_ct_supported]
struct SCTAuditingConfiguration {
  // The sampling rate for SCT auditing reports.
  double sampling_rate;

  // How long Chrome will wait before assuming a new SCT has been ingested by
  // the log.
  mojo_base.mojom.TimeDelta log_expected_ingestion_delay;

  // The maximum random delay that may be added to
  // |log_expected_ingestion_delay|.
  mojo_base.mojom.TimeDelta log_max_ingestion_random_delay;

  // The URL where reports should be sent.
  url.mojom.Url report_uri;

  // An annotated URL template for hashdance lookup queries. $1 should be in
  // place of the "length" parameter, and $2 in place of the "prefix" parameter.
  url.mojom.Url hashdance_lookup_uri;

  // Traffic annotation for the report request.
  MutableNetworkTrafficAnnotationTag traffic_annotation;

  // Traffic annotation for the hashdance lookup query.
  MutableNetworkTrafficAnnotationTag hashdance_traffic_annotation;
};

// GssapiLibraryLoadObserver will be notified once when GSSAPI libraries
// are about to be loaded, on a "WWW_Authenticate: negotiate" header.
[EnableIf=is_linux]
interface GssapiLibraryLoadObserver {
  // Called only once per network service.
  OnBeforeGssapiLibraryLoad();
};

// Implemented by the network service. The browser process sends messages to
// the network service over this interface.
//
// This is a trusted interface that only the browser process should have access
// to. It must not be sent to any untrusted process like a renderer process.
// The network sandbox may be disabled (to kNoSandbox) by policy, and may not
// be available on all platforms.
[ServiceSandbox=sandbox.mojom.Sandbox.kNetwork]
interface NetworkService {
  // Sets the parameters and initializes the service.
  SetParams(NetworkServiceParams params);

  // Starts observing the NetLog event stream and writing entries to |file| with
  // a maximum size specified by |max_total_size|. |constants| is a legend used
  // for decoding constant values in the log; it will be merged with the
  // |GetNetConstants()| dictionary before being passed through to the
  // FileObserver. (See |FileNetLogObserver::CreateBounded()| for more details).
  // Most clients will just be adding a dictionary under the key "clientInfo".
  // If |max_total_size| is net::FileNetLogObserver::kNoLimit then the log has
  // an unbounded size.
  //
  // Note that maximum size is only a rough limit and the final file size may
  // differ by a small amount from the requested value.
  StartNetLog(mojo_base.mojom.File file,
              uint64 max_total_size,
              NetLogCaptureMode capture_mode,
              mojo_base.mojom.DictionaryValue constants,
              mojo_base.mojom.TimeDelta? duration);

  // Attaches an external source of NetLog events. Control events will be sent
  // to the |proxy_source| pipe indicating when netlogging is active, the
  // NetLog events should be sent to the |proxy_sink| pipe, and must use a
  // non-conflicting source id space.
  AttachNetLogProxy(pending_remote<NetLogProxySource> proxy_source,
                    pending_receiver<NetLogProxySink> proxy_sink);

  // Starts logging SSL key material to the |file|. This must be called before
  // any SSL connections are made. (See |SSLClientSocket::SetSSLKeyLogger()|
  // for more details).
  SetSSLKeyLogFile(mojo_base.mojom.File file);

  // Creates a new network context with the given parameters.
  [AllowedContext=sandbox.mojom.Context.kBrowser]
  CreateNetworkContext(
      pending_receiver<NetworkContext> context, NetworkContextParams params);

  // Configures whether the built-in stub host resolver is used in preference
  // over getaddrinfo. When enabled, the stub resolver will attempt to use the
  // system's DNS settings to do DNS lookups itself. See
  // https://tools.ietf.org/html/rfc1034#section-5.3.1 for definition of a stub
  // resolver.
  //
  // `dns_over_https_config` provides zero or more DNS over HTTPS servers.
  // DnsTransactions will by default follow the behavior of `secure_dns_mode`.
  // In SECURE mode, only DoH lookups will be performed. In AUTOMATIC mode,
  // DoH lookups to available servers will be performed first, and insecure
  // lookups will be used as a fallback. In OFF mode, only insecure lookups will
  // be performed. When insecure lookups are performed, they will be sent by
  // the async resolver first if `insecure_dns_client_enabled` is true and
  // then by the system resolver as a fallback.
  //
  // DNS over HTTPS will use the primary NetworkContext, so can only be enabled
  // after the primary network context has been created. Other than that
  // limitation, this method can be called at any time to change DNS
  // configuration, though calling it will fail any DNS lookups that have
  // already been started.
  //
  // `additional_dns_types_enabled` controls whether additional DNS query types,
  // e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA
  // queries when a request is being made via insecure DNS. Has no effect on
  // Secure DNS which always allows additional types.
  //
  // `happy_eyeballs_v3_enabled` controls whether the Happy Eyeballs V3 is
  //  enabled.
  //
  // `fallback_doh_nameservers` may be used in AUTOMATIC mode if falling back to
  // DoH is preferred to falling back to insecure DNS. If these nameservers are
  // successfully upgraded to DoH, they are used in the order defined by
  // `net::ResolveContext::GetDohIterator`.
  ConfigureStubHostResolver(bool insecure_dns_client_enabled,
                            bool happy_eyeballs_v3_enabled,
                            SecureDnsMode secure_dns_mode,
                            DnsOverHttpsConfig dns_over_https_config,
                            bool additional_dns_types_enabled,
                            array<IPEndPoint> fallback_doh_nameservers);

  // Disables QUIC for the NetworkService. Affects all existing NetworkContexts,
  // and all new ones that are created. Once called, QUIC cannot be re-enabled.
  DisableQuic();

  // Configures HTTP authentication for all NetworkContexts created using the
  // NetworkService. May only be called at most once, and may only be called
  // before any NetworkContexts are created.
  //
  // If this method is not invoked, default values will be used (which currently
  // allow all supported schemes on the current platform).
  SetUpHttpAuth(HttpAuthStaticParams http_auth_static_params);

  // Sets global auth params. Unlike SetUpAuth(), may be called multiple times,
  // at any point in time. Affects all NetworkContexts, both already existing
  // one and subsequently created ones.
  ConfigureHttpAuthPrefs(HttpAuthDynamicParams http_auth_dynamic_params);

  // Specifies whether requests for raw headers coming through URLLoaderFactory
  // associated with the specified process will be granted. Only raw headers
  // for requests with URLs matching a listed origin will be reported (this
  // permission has no effect on the network request itself).
  // The list overwrites the list set for given process with a previous call
  // to this method.
  // Granting a permission increases risks in case the child process becomes
  // compromised, so this should be done only in specific cases
  // (e.g. DevTools attached).
  SetRawHeadersAccess(int32 process_id, array<url.mojom.Origin> origins);

  // Sets the maximum number of connections for a proxy chain.
  //   * Values larger than 99 will saturate to 99.
  //   * Values smaller than 6 will saturate to 6.
  SetMaxConnectionsPerProxyChain(uint32 max_connections);

  // Gets the NetworkChangeManager.
  GetNetworkChangeManager(
      pending_receiver<NetworkChangeManager> network_change_manager);

  // Gets the NetworkQualityEstimatorManager.
  GetNetworkQualityEstimatorManager(
      pending_receiver<NetworkQualityEstimatorManager> receiver);

  // Gets the DnsConfigChangeManager.
  GetDnsConfigChangeManager(
      pending_receiver<DnsConfigChangeManager> receiver);

  // Gets list of network interfaces.
  // The |policy| parameter is a flag that specifies whether to include/exclude
  // network interfaces. Corresponds to enum net::HostAddressSelectionPolicy.
  GetNetworkList(uint32 policy) => (array<NetworkInterface>? networks);

  // Notification that the certificate trust store has been modified.
  OnTrustStoreChanged();

  // Notification that the client certificate store has been modified.
  OnClientCertStoreChanged();

  // Send the encryption key to the network service to use for AES encryption.
  SetEncryptionKey(mojo_base.mojom.ByteString encryption_key);

  // Called when the system is low on memory.
  OnMemoryPressure(
      mojo_base.mojom.MemoryPressureLevel memory_pressure_level);

  // Called when there is a change in the current count of peer to peer
  // connections that may require low latency.
  OnPeerToPeerConnectionsCountChange(uint32 count);

  // Called on state changes of the Android application.
  [EnableIf=is_android]
  OnApplicationStateChange(mojo_base.mojom.ApplicationState state);

  // Sets Trust Tokens key commitment state. |raw_commitments| is the
  // JSON-encoded string representation of a collection of issuers' key
  // commitments according to the format specified, for now, in the Trust
  // Tokens design doc:
  // https://docs.google.com/document/d/1TNnya6B8pyomDK2F1R9CL3dY10OAmqWlnCxsWyOBDVQ/edit#heading=h.z52drgpfgulz.
  SetTrustTokenKeyCommitments(string raw_commitments) => ();

  // Clears the SCT auditing cache.
  [EnableIf=is_ct_supported]
  ClearSCTAuditingCache();

  // Configures SCT auditing.
  [EnableIf=is_ct_supported]
  ConfigureSCTAuditing(SCTAuditingConfiguration configuration);

  // Updates the log list used for CT auditing.
  [EnableIf=is_ct_supported]
  UpdateCtLogList(array<CTLogInfo> log_list) => ();

  // Updates the list of popular SCTs queried during CT hashdance auditing.
  [EnableIf=is_ct_supported]
  UpdateCtKnownPopularSCTs(array<array<uint8>> sct_hashes) => ();

  // Disables or enables CT Enforcement.
  [EnableIf=is_ct_supported]
  SetCtEnforcementEnabled(bool enabled) => ();

  // Updates the key pinnning pin list. `update_time` should contain the
  // timestamp that the pins list was considered fresh/current, in order to
  // ensure that key pinning is not enforced if the list is too out of date.
  UpdateKeyPinsList(PinList pin_list, mojo_base.mojom.Time update_time);

  // Calls base::debug::DumpWithoutCrashing for the network process.
  // TODO(http://crbug.com/934317): Remove this once done debugging renderer
  // hangs.
  [EnableIf=is_android]
  DumpWithoutCrashing(mojo_base.mojom.Time dump_request_time);

  // Binds the test service's testing interface. Available only in some test
  // environments.
  BindTestInterfaceForTesting(pending_receiver<NetworkServiceTest> receiver);

  // Sets the global First-Party Sets data.
  //
  // Only the first call can have any effect, subsequent invocations are
  // ignored.
  SetFirstPartySets(GlobalFirstPartySets sets);

  // Sets the list of ports which will be permitted even if they normally would
  // be restricted.
  SetExplicitlyAllowedPorts(array<uint16> ports);

  // Parses response headers and returns a structured version to the caller.
  // This call originates from the browser process. Used for navigations when
  // the URLLoader didn't provide ParsedHeader in the first place. This happens
  // when the raw headers represent untrustworthy input and the URLLoader used
  // lives in a non-sandboxed process. It can also happen from some exotic
  // URLLoader where parsing hasn't been implemented.
  // In particular, this is used for request served from WebBundle,
  // Extensions, etc.
  ParseHeaders(url.mojom.Url url, HttpResponseHeaders headers)
      => (ParsedHeaders parsed_headers);

  // Enables or disables whether URLLoaders need to call
  // URLLoaderNetworkServiceObserver::OnDataUseUpdate. By default it's not
  // enabled.
  EnableDataUseUpdates(bool enable);

  // Set IPv6 reachability override. When `reachability_override` is true, the
  // DNS stack queries AAAA record even when the IPv6 reachability probe fails.
  SetIPv6ReachabilityOverride(bool reachability_override);

  // Set the GssapiLibraryLoadObserver for this network service.
  // Will only be notified once unless the observer is set again.
  // TODO(crbug.com/40070096): remove this observer once GSSAPI is brokered
  // out of the network service.
  [EnableIf=is_linux]
  SetGssapiLibraryLoadObserver(
      pending_remote<GssapiLibraryLoadObserver> gssapi_library_load_observer);

  // Set NetworkAnnotationMonitor remote. This allows network calls to be
  // reported via `NotifyNetworkRequestWithAnnotation`.
  SetNetworkAnnotationMonitor(
      pending_remote<network.mojom.NetworkAnnotationMonitor> remote);

  // SetTpcdMetadataGrants syncs the TPCD Metadata Grants copy of the network
  // service with that of the browser.
  SetTpcdMetadataGrants(
      array<content_settings.mojom.ContentSettingPatternSource> settings);

  // Set up a content decoding interceptor for an existing URLLoader connection.
  // This is typically used by the browser process when client-side decoding was
  // initially requested, but the final consumer of the response body resides in
  // the browser process (e.g., for downloads or Signed Exchanges) rather than
  // the renderer.
  //
  // The interceptor reads the encoded data from the `source_body` pipe, decodes
  // it according to the specified `content_encoding_types`, and writes the
  // decoded data to the `dest_body` pipe. It manages the communication flow
  // between the original URLLoader/URLLoaderClient pair (`source_url_loader`,
  // `source_url_loader_client`) and presents a new pair (`dest_url_loader`,
  // `dest_url_loader_client`) for the ultimate consumer to interact with.
  InterceptUrlLoaderForBodyDecoding(
      array<SourceType> content_encoding_types,
      handle<data_pipe_consumer> source_body,
      handle<data_pipe_producer> dest_body,
      pending_remote<URLLoader> source_url_loader,
      pending_receiver<URLLoaderClient> source_url_loader_client,
      pending_receiver<URLLoader> dest_url_loader,
      pending_remote<URLLoaderClient> dest_url_loader_client);

  // Decodes a data stream with the specified content encodings. This is a
  // utility function for decoding a stream of bytes. It reads from
  // `source_body`, decodes the data according to `content_encoding_types`, and
  // writes the result to `dest_body`. Returns net::OK on success, or a net
  // error code on failure (e.g. a decoding error).
  // If a decoding error occurs mid-stream, `dest_body` will contain the data
  // that was successfully decoded before the failure, and the callback will be
  // called with net::ERR_CONTENT_DECODING_FAILED.
  //
  // This is used when ResourceRequest.client_side_content_decoding_enabled is
  // true, which prevents the response body from being decoded on the network
  // service side, and there is a need to check the decoded response body on the
  // browser process side (e.g. DevTools).
  DecodeContentEncoding(
      array<SourceType> content_encoding_types,
      handle<data_pipe_consumer> source_body,
      handle<data_pipe_producer> dest_body) => (int32 error_code);

  // Enables or disables TLS 1.3 Early Data.
  SetTLS13EarlyDataEnabled(bool enabled);
};