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/file.mojom";
import "mojo/public/mojom/base/file_path.mojom";
import "services/network/public/mojom/cookie_manager.mojom";
import "services/network/public/mojom/network_change_manager.mojom";
import "services/network/public/mojom/network_context.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/network_quality_estimator_manager.mojom";
import "services/network/public/mojom/signed_tree_head.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

// The content/browser implementation of this SSLPrivateKey interface wraps the
// scoped_refptr<net::SSLPrivateKey> that is received from
// SSLClientAuthDelegate::ContinueWithCertificate(), and this mojo interface is
// sent from content/browser to services/network so that services/network can
// have its own net::SSLPrivateKey implementation that internally uses this mojo
// interface.
// The |algorithm| and |input| parameters correspond to the |algorithm| and
// |input| parameters in net::SSLPrivateKey::Sign().
// The |net_error| and |signature| parameters correspond to the parameters in
// net::SSLPrivateKey::SignCallback.
interface SSLPrivateKey {
  Sign(uint16 algorithm,
       array<uint8> input) => (int32 net_error, array<uint8> signature);
};

// The |credentials| output parameter is given to URLRequest::SetAuth()
// through this mojo interface. It is not set when URLRequest::CancelAuth()
// needs to be called.
interface AuthChallengeResponder {
   OnAuthCredentials(AuthCredentials? credentials);
};

// Network service interface to the browser.
interface NetworkServiceClient {
  // Called when we receive an authentication failure.
  // The |auth_challenge_responder| will respond to auth challenge with
  // credentials. |head| can provide response headers for the response
  // which has elicited this auth request, if applicable.
  OnAuthRequired(uint32 process_id,
                 uint32 routing_id,
                 uint32 request_id,
                 url.mojom.Url url,
                 url.mojom.Url site_for_cookies,
                 bool first_auth_attempt,
                 AuthChallengeInfo auth_info,
                 int32 resource_type,
                 URLResponseHead? head,
                 AuthChallengeResponder auth_challenge_responder);
  // Called when an SSL certificate requested message is received for client
  // authentication.
  // The |algorithm_preferences| parameter corresponds to the return value
  // of net::SSLPrivateKey::GetAlgorithmPreferences().
  // The |cancel_certificate_selection| parameter is used to distinguish
  // between the following two cases because the |x509_certificate| will be
  // nullptr in both cases:
  // 1. The connection is continued with no client cert,
  // net::URLRequest::ContinueWithCertificate(nullptr, nullptr) needs to be
  // called.
  // 2. The request is aborted, net::URLRequest::CancelWithError() needs to be
  // called.
  OnCertificateRequested(uint32 process_id,
                         uint32 routing_id,
                         uint32 request_id,
                         network.mojom.SSLCertRequestInfo cert_info) => (
                             network.mojom.X509Certificate x509_certificate,
                             array<uint16> algorithm_preferences,
                             SSLPrivateKey ssl_private_key,
                             bool cancel_certificate_selection);
  // Called when an SSL certificate is encountered.
  // The callback argument is a net::ERROR value. If it's net::OK, then the
  // request is resumed. Otherwise it's cancelled with the given error.
  OnSSLCertificateError(uint32 process_id,
                        uint32 routing_id,
                        uint32 request_id,
                        int32 resource_type,
                        url.mojom.Url url,
                        SSLInfo ssl_info,
                        bool fatal) => (int32 net_error);
  // Called when file uploading was requested.
  // If the process that requested the uploads has permission to read all of
  // the files referenced by |file_paths|, the callback arguments will be
  // net::OK, along with an array of open file handles. The array will contain
  // exactly one handle for each path in |file_paths|, in the same order.
  // If any files referenced by |file_paths| cannot be read, a net::ERROR will
  // be returned, and |files| will be an empty list. If the |async| parameter
  // is true, the files will be opened with FLAG_ASYNC.
  OnFileUploadRequested(uint32 process_id,
                        bool async,
                        array<mojo_base.mojom.FilePath> file_paths) =>
                        (int32 net_error, array<mojo_base.mojom.File> files);

  // Called when an attempt has been made to set |cookie|.
  OnCookieChange(
      int32 process_id, int32 routing_id, url.mojom.Url url,
      url.mojom.Url frame_url, CanonicalCookie cookie, bool blocked_by_policy);

  // Called when an attempt has been made to read the cookies in |cookie_list|.
  OnCookiesRead(
      int32 process_id, int32 routing_id, url.mojom.Url url,
      url.mojom.Url frame_url, array<CanonicalCookie> cookie_list,
      bool blocked_by_policy);
};

// An HTTPS server to send DNS queries to, per the DNS Queries over HTTPS spec.
// spec:  https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-07
 struct DnsOverHttpsServer {
  // DNS over HTTPS server URL. Must be HTTPS.
  url.mojom.Url url;

  // Whether to use POSTs to do DNS lookups. Otherwise, GETs are used. See spec
  // for more details.
  bool use_posts = false;
};

// 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
  // (OS_POSIX && !OS_ANDROID && !OS_CHROMEOS && OS_IOS) platforms.
  string gssapi_library_name;

  // Indicates whether the GSSAPI library should be loaded. Only supported on
  // ChromeOS.
  bool allow_gssapi_library_load = true;
};

// Values for configurating HTTP authentication that can be changed as needed.
struct HttpAuthDynamicParams {
  // Comma / semi-colon delimited whitelist of server origins which the network
  // service may send the default credentials for NTLM or Negotiate
  // authentication.
  string server_whitelist;

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

  // 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 = true;

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

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

// Browser interface to the network service.
interface NetworkService {
  SetClient(NetworkServiceClient client);

  // Creates a new network context with the given parameters.
  CreateNetworkContext(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 an optional list of DNS over HTTPS servers.
  // When populated, all DNS lookups will try to use DNS over HTTPS in the order
  // the servers are provided in and will only fall back to using system
  // settings if DNS over HTTPS fails. It is illegal to have a populated
  // |dns_over_https_servers| when |stub_resolver_enabled| is false.
  //
  // 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.
  //
  // Both the stub resolver and DNS over HTTPS are disabled by default.
  ConfigureStubHostResolver(bool stub_resolver_enabled,
                            array<DnsOverHttpsServer>? dns_over_https_servers);

  // 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. Granting such 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(uint32 process_id, bool allow);

  // Gets the NetworkChangeManager.
  GetNetworkChangeManager(
      NetworkChangeManager& network_change_manager);

  // Gets the NetworkQualityEstimatorManager.
  GetNetworkQualityEstimatorManager(
      NetworkQualityEstimatorManager& network_quality_estimator_manager);

  // Gets the accumulated network usage since the start/restart of the service.
  GetTotalNetworkUsages() => (array<NetworkUsage> total_network_usages);

  // Update Signed Tree Heads (STH) used in the handling of Certificate
  // Transparency. Broadcast to each NetworkContext using the NetworkService.
  // NetworkContextes ignore STHs from unrecognized logs.
  UpdateSignedTreeHead(SignedTreeHead signed_tree_head);
};