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 "mojo/public/mojom/base/memory_pressure_level.mojom";
import "mojo/public/mojom/base/read_only_buffer.mojom";
import "mojo/public/mojom/base/string16.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "mojo/public/mojom/base/values.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/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/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/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

[EnableIf=is_android]
import "mojo/public/mojom/base/application_state.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);
};

// This interface enables the UI to send client certificate selections back to
// the network service.
//
// Defining an interface for this purpose, rather than using a union in the
// response of OnCertificateRequested, enables the NetworkServiceClient to learn
// of the URLLoader destruction via the connection error handler.
interface ClientCertificateResponder {
  // Use the selected certificate and continue the URLRequest.
  //
  // - |provider_name| corresponds to the return value of
  //   net::SSLPrivateKey::GetProviderName().
  // - |algorithm_preferences| corresponds to the return value of
  //   net::SSLPrivateKey::GetAlgorithmPreferences().
  ContinueWithCertificate(network.mojom.X509Certificate x509_certificate,
                          string provider_name,
                          array<uint16> algorithm_preferences,
                          SSLPrivateKey ssl_private_key);

  // Affirmatively select no certificate (this is cached and can affect future
  // URLRequests). Does not cancel the URLRequest.
  //
  // The connection is continued with no client cert.
  // net::URLRequest::ContinueWithCertificate(nullptr, nullptr) needs to be
  // called.
  ContinueWithoutCertificate();

  // Cancel the URLRequest. The request is aborted.
  // net::URLRequest::CancelWithError() needs to be called.
  CancelRequest();
};

struct LoadInfo {
  uint32 process_id;
  uint32 routing_id;
  string host;
  uint32 load_state;  // net::LoadState enum
  mojo_base.mojom.String16 state_param;
  uint64 upload_position;
  uint64 upload_size;
};

// 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.
  //
  // |window_id| or else |process_id| and |routing_id| indicates
  // the frame making the request, see
  // network::ResourceRequest::fetch_window_id.
  OnAuthRequired(mojo_base.mojom.UnguessableToken? window_id,
                 uint32 process_id,
                 uint32 routing_id,
                 uint32 request_id,
                 url.mojom.Url url,
                 bool first_auth_attempt,
                 AuthChallengeInfo auth_info,
                 URLResponseHead? head,
                 AuthChallengeResponder auth_challenge_responder);

  // Called when an SSL certificate requested message is received for client
  // authentication.
  //
  // Rather than using one response for multiple purposes, the caller expects
  // exactly one response (or disconnect) to be sent back via |cert_responder|.
  //
  // |window_id| or else |process_id| and |routing_id| indicates the frame
  // making the request, see network::ResourceRequest::fetch_window_id.
  OnCertificateRequested(mojo_base.mojom.UnguessableToken? window_id,
                         uint32 process_id,
                         uint32 routing_id,
                         uint32 request_id,
                         network.mojom.SSLCertRequestInfo cert_info,
                         ClientCertificateResponder cert_responder);

  // 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,
                        url.mojom.Url url,
                        int32 net_error,
                        SSLInfo ssl_info,
                        bool fatal) => (int32 net_error);

  // Notification that a trust anchor was used for the given user.
  // |username_hash| was the parameter passed in NetworkContextParams.
  [EnableIf=is_chromeos]
  OnTrustAnchorUsed(string username_hash);

  // 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 periodically to update the client about progress of the current
  // loads. To avoid flooding the client, it has to ack the update before it can
  // receive the next update.
  OnLoadingStateUpdate(array<LoadInfo> infos) => ();

  // Called on every request completion to update the network traffic annotation
  // ID, and the total bytes received and sent.
  // |network_traffic_annotation_id_hash| represents the hash of unique tag that
  // identifies the annotation of the request.
  OnDataUseUpdate(int32 network_traffic_annotation_id_hash, int64 recv_bytes,
                  int64 sent_bytes);

  // Called to generate an auth token for SPNEGO authentication on Android.
  [EnableIf=is_android]
  OnGenerateHttpNegotiateAuthToken(string server_auth_token, bool can_delegate,
                                   string auth_negotiate_android_account_type,
                                   string spn) =>
                                   (int32 result, string auth_token);

  // Called to send raw header information and information about excluded
  // cookies. Only called when |devtool_request_id| is available to the
  // URLLoader.
  OnRawRequest(
    int32 process_id,
    int32 routing_id,
    string devtool_request_id,
    array<CookieWithStatus> cookies_with_status,
    array<HttpRawHeaderPair> headers);

  // Called to send information about the cookies blocked from storage from a
  // received response. Only called when |devtool_request_id| is available to
  // the URLLoader.
  OnRawResponse(
    int32 process_id,
    int32 routing_id,
    string devtool_request_id,
    array<CookieAndLineWithStatus> cookies_with_status,
    array<HttpRawHeaderPair> headers,
    string? raw_response_headers);
};

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

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

// Values for configuring OSCrypt.
[EnableIf=needs_crypt_config]
struct CryptConfig {
  // Force OSCrypt to use a specific linux password store.
  string store;

  // The product name to use for permission prompts.
  string product_name;

  // Controls whether preference on using or ignoring backends is used.
  bool should_use_preference;

  // Preferences are stored in a separate file in the user data directory.
  mojo_base.mojom.FilePath user_data_path;
};

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

// Information about how logging should be configured.
// Corresponds to logging::LoggingSettings.
[EnableIf=is_chromeos]
struct LoggingSettings {
  uint32 logging_dest;
  mojo_base.mojom.FilePath log_file;
};

// Browser interface to the network service.
interface NetworkService {
  // Sets client used by all |NetworkContext|s creating by |NetworkService|.
  // Pending requests may hang if the |client| pipe is closed before they
  // complete.
  SetClient(NetworkServiceClient client, 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]
  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);

  // Starts logging SSL key material to the |file|. This must be called before
  // any SSL connections are made. (See |SSLClientSocket::SetSSLKeyLogger()|
  // for more details).
  // TODO(crbug.com/841001) This should pass a File which has already been
  // opened to be sandbox friendly.
  SetSSLKeyLogFile(mojo_base.mojom.FilePath file);

  // 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. 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(uint32 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(
      NetworkChangeManager& network_change_manager);

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

  // Gets the DnsConfigChangeManager.
  GetDnsConfigChangeManager(DnsConfigChangeManager& dns_config_change_manager);

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

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

  // Sets up OSCrypt for the network service process. Must be called before
  // encrypted cookies can be read or set.
  [EnableIf=needs_crypt_config]
  SetCryptConfig(CryptConfig crypt_config);

  // Send the encryption key to the network service to use for AES encryption.
  [EnableIf=is_mac]
  SetEncryptionKey(string encryption_key);

  // Notifies CORB (Cross-Origin Read Blocking) that |process_id| is proxying
  // requests on behalf of a universal-access plugin and therefore CORB should
  // stop blocking requests marked as ResourceType::kPluginResource.
  //
  // TODO(lukasza, laforge): https://crbug.com/702995: Remove the ...ForPlugin
  // methods once Flash support is removed from Chromium (probably around 2020
  // - see https://www.chromium.org/flash-roadmap).
  AddCorbExceptionForPlugin(uint32 process_id);

  // Reverts AddCorbExceptionForPlugin.
  RemoveCorbExceptionForPlugin(uint32 process_id);

  // Registers additional MIME types that can be protected by CORB (without any
  // confirmation sniffing).
  //
  // TODO(lukasza): https://crbug.com/944162: Remove the method below once
  // kMimeHandlerViewInCrossProcessFrame feature ships.
  AddExtraMimeTypesForCorb(array<string> mime_types);

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