services/network/public/mojom/network_service.mojom

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

module network.mojom;

import "mojo/public/mojom/base/byte_string.mojom";
import "mojo/public/mojom/base/file.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "mojo/public/mojom/base/memory_pressure_level.mojom";
import "mojo/public/mojom/base/read_only_buffer.mojom";
import "mojo/public/mojom/base/read_only_file.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "mojo/public/mojom/base/values.mojom";
import "sandbox/policy/mojom/sandbox.mojom";
import "services/network/public/mojom/cookie_manager.mojom";
import "services/network/public/mojom/host_resolver.mojom";
import "services/network/public/mojom/http_raw_headers.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_change_manager.mojom";
import "services/network/public/mojom/network_context.mojom";
import "services/network/public/mojom/ip_address_space.mojom";
import "services/network/public/mojom/network_interface.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/trust_tokens.mojom";
import "services/network/public/mojom/parsed_headers.mojom";
import "services/network/public/mojom/url_loader_network_service_observer.mojom";
import "services/network/public/mojom/url_request.mojom";
import "services/network/public/mojom/url_response_head.mojom";
import "services/network/public/mojom/client_security_state.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 {
  // List of supported auth schemes. Unrecognized schemes are ignored.
  // The default value of this field (an empty list) does not match default
  // behavior of NetworkService when no HttpAuthStaticParams is specified.
  array<string> supported_schemes;

  // 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 {
  // 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.
  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;

  // 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;
};

// Information about how logging should be configured.
// Corresponds to logging::LoggingSettings.
[EnableIf=is_chromeos_ash]
struct LoggingSettings {
  uint32 logging_dest;
  handle<platform> log_file_descriptor;
};

// 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);

  // Reinitializes the Network Service's logging with the given settings. This
  // is needed on Chrome OS, which switches to a log file in the user's home
  // directory once they log in.
  [EnableIf=is_chromeos_ash]
  ReinitializeLogging(LoggingSettings settings);

  // Starts observing the NetLog event stream and writing entries to |file|.
  // |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".
  StartNetLog(mojo_base.mojom.File file,
              NetLogCaptureMode capture_mode,
              mojo_base.mojom.DictionaryValue constants);

  // 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.
  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_servers` is a list of 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.
  ConfigureStubHostResolver(bool insecure_dns_client_enabled,
                            SecureDnsMode secure_dns_mode,
                            array<DnsOverHttpsServer> dns_over_https_servers,
                            bool additional_dns_types_enabled);

  // 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 server.
  //   * Negative values will set the default proxy connection limit (32)
  //   * Values larger than 99 will saturate to 99.
  //   * Values smaller than 6 will saturate to 6.
  SetMaxConnectionsPerProxy(int32 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);

  // Updates the CRLSet used in the verification of certificates. CRLSets that
  // cannot be parsed using net::CRLSet::Parse will be ignored, as will older
  // CRLSets (where older is determined by the sequence number). All Network
  // Contexts created by the Network Service, including those created after
  // this call, will use the same CRLSet.
  UpdateCRLSet(mojo_base.mojom.ReadOnlyBuffer crl_set) => ();

  // Notification that the certificate database has been modified.
  OnCertDBChanged();

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

  // Notifies |request_initiator_origin_lock| enforcement code that |process_id|
  // is proxying requests on behalf of a plugin from
  // |allowed_request_initiator| origin.
  //
  // TODO(lukasza, kmoon): https://crbug.com/702993: Remove the code here once
  // PDF support doesn't depend on PPAPI anymore.
  AddAllowedRequestInitiatorForPlugin(
      int32 process_id,
      url.mojom.Origin allowed_request_initiator);

  // Reverts AddAllowedRequestInitiatorForPlugin.
  RemoveSecurityExceptionsForPlugin(int32 process_id);

  // 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 the given environment variables in the network service's process.
  // This method won't modify variables that aren't present in the
  // |environment| array.
  SetEnvironment(array<EnvironmentVariable> environment);

  // 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.
  // This allows the embedder to specify whether SCT auditing should be enabled,
  // what sampling rate to use on reports, where reports should be sent, and the
  // traffic annotation to use.
  [EnableIf=is_ct_supported]
  ConfigureSCTAuditing(bool enabled,
                       double sampling_rate,
                       url.mojom.Url report_uri,
                       MutableNetworkTrafficAnnotationTag traffic_annotation);


  // Updates the log list used for CT verification. `update_time` should
  // contain the timestamp that the log list was considered fresh/current, in
  // order to ensure that CT is not enforced if the log list is too out of
  // date.
  [EnableIf=is_ct_supported]
  UpdateCtLogList(array<CTLogInfo> log_list, mojo_base.mojom.Time update_time);

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

  // 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.
  BindTestInterface(pending_receiver<NetworkServiceTest> receiver);

  // Sets the First-Party Sets data. |sets_file| is the file containing a
  // collection of set declarations according to the format specified in this
  // document: https://github.com/privacycg/first-party-sets. The collection may
  // either be a single JSON array of such records, or a sequence of
  // newline-delimited JSON objects (one per line). Note that only the first
  // invocation will have any effect. On any kind of error, this method has no
  // effect.
  //
  // |sets_file| may be invalid ("nullopt"), if no such file exists on the
  // client's device (i.e. if the First-Party Sets component has not been
  // installed yet).  Such a case is considered the same as if the file's
  // contents were empty.
  SetFirstPartySets(mojo_base.mojom.ReadOnlyFile? sets_file);

  // Sets the First-Party Sets data that was persisted to compare it with the
  // current First-Party Sets data set by `SetFirstPartySets()`, which is
  // considered more up-to-date, and returns a serialized version of the current
  // one. Both input and output are in format of the JSON-encoded string
  // representation of a map of site -> site.
  SetPersistedFirstPartySetsAndGetCurrentSets(string persisted_sets)
      => (string up_to_date_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);
};