| // 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 "components/content_settings/core/common/content_settings_types.mojom"; |
| import "mojo/public/mojom/base/time.mojom"; |
| import "sandbox/policy/mojom/context.mojom"; |
| import "services/network/public/mojom/cookie_partition_key.mojom"; |
| import "services/network/public/mojom/first_party_sets.mojom"; |
| import "services/network/public/mojom/schemeful_site.mojom"; |
| import "url/mojom/url.mojom"; |
| |
| // Parameters for constructing a cookie manager. |
| struct CookieManagerParams { |
| // Whether or not third party cookies should be blocked. |
| bool block_third_party_cookies = false; |
| |
| // Whether tracking protection for 3PCD (prefs + UX) is enabled. |
| bool tracking_protection_enabled_for_3pcd = false; |
| |
| // Whether Third Party Cookie Deprecation mitigations efforts such as Third |
| // Party Cookie Deprecation Metadata grants are permitted. |
| bool mitigations_enabled_for_3pcd = false; |
| |
| // Content settings for CookieManager. |
| map<content_settings.mojom.ContentSettingsType, |
| array<content_settings.mojom.ContentSettingPatternSource>> content_settings; |
| |
| // Schemes that unconditionally allow cookies from secure origins. |
| array<string> secure_origin_cookies_allowed_schemes; |
| |
| // Schemes that unconditionally allow cookies from the same scheme. |
| array<string> matching_scheme_cookies_allowed_schemes; |
| |
| // Schemes that unconditionally allow third party cookies. |
| array<string> third_party_cookies_allowed_schemes; |
| |
| // Whether or not to allow cookies for file:// URLs. Can be overridden by |
| // CookieManager.AllowFileSchemeCookies(). |
| bool allow_file_scheme_cookies = false; |
| |
| // The type of CookieAccessDelegate to pass to the underlying CookieStore. |
| // If these params are not present, CookieManager defaults to using |
| // USE_CONTENT_SETTINGS. |
| CookieAccessDelegateType cookie_access_delegate_type = USE_CONTENT_SETTINGS; |
| }; |
| |
| enum CookieAccessDelegateType { |
| // Decides access semantics based on the content settings it was constructed |
| // with. |
| USE_CONTENT_SETTINGS, |
| // Always returns Legacy access semantics. |
| ALWAYS_LEGACY, |
| // Always returns Non-Legacy access semantics. |
| ALWAYS_NONLEGACY, |
| }; |
| |
| enum CookiePriority { |
| LOW, |
| MEDIUM, |
| HIGH |
| }; |
| |
| enum CookieSourceScheme { |
| kUnset, |
| kNonSecure, |
| kSecure, |
| }; |
| |
| // See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 |
| // and https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis for |
| // information about same site cookie restrictions. |
| // Keep in sync with net/cookies/cookie_constants.h. |
| // Note: Don't renumber, as these values are persisted to a database. |
| enum CookieSameSite { |
| UNSPECIFIED = -1, |
| NO_RESTRICTION = 0, |
| LAX_MODE = 1, |
| STRICT_MODE = 2, |
| // Reserved 3 (was EXTENDED_MODE), next number is 4. |
| }; |
| |
| enum CookieEffectiveSameSite { |
| kNoRestriction = 0, |
| kLaxMode = 1, |
| kStrictMode = 2, |
| kLaxModeAllowUnsafe = 3, |
| kUndefined = 4, |
| }; |
| |
| // Defined in net::CookieInclusionStatus::ExemptionReason. |
| enum CookieExemptionReason { |
| kNone = 0, |
| kUserSetting = 1, |
| k3PCDMetadata = 2, |
| k3PCDDeprecationTrial = 3, |
| k3PCDHeuristics = 4, |
| kEnterprisePolicy = 5, |
| kStorageAccess = 6, |
| kTopLevelStorageAccess = 7, |
| kCorsOptIn = 8, |
| kScheme = 9, |
| }; |
| |
| enum ContextType { |
| CROSS_SITE, |
| SAME_SITE_LAX_METHOD_UNSAFE, |
| SAME_SITE_LAX, |
| SAME_SITE_STRICT |
| }; |
| |
| enum CookieSameSiteContextMetadataDowngradeType { |
| kNoDowngrade, |
| kStrictToLax, |
| kStrictToCross, |
| kLaxToCross, |
| }; |
| |
| enum CookieSourceType { |
| kUnknown, |
| kHTTP, |
| kScript, |
| kOther, |
| }; |
| |
| enum ContextRedirectTypeBug1221316 { |
| kUnset, |
| kNoRedirect, |
| kCrossSiteRedirect, |
| kPartialSameSiteRedirect, |
| kAllSameSiteRedirect, |
| }; |
| |
| enum HttpMethod { |
| kUnset, |
| kUnknown, |
| kGet, |
| kHead, |
| kPost, |
| KPut, |
| kDelete, |
| kConnect, |
| kOptions, |
| kTrace, |
| kPatch, |
| }; |
| |
| // Keep defaults here in sync with net/cookies/cookie_options.h. |
| struct CookieSameSiteContextMetadata { |
| CookieSameSiteContextMetadataDowngradeType cross_site_redirect_downgrade = kNoDowngrade; |
| ContextRedirectTypeBug1221316 redirect_type_bug_1221316 = kUnset; |
| HttpMethod http_method_bug_1221316 = kUnset; |
| }; |
| |
| // Keep defaults here in sync with net/cookies/cookie_options.h. |
| struct CookieSameSiteContext { |
| ContextType context = CROSS_SITE; |
| ContextType schemeful_context = CROSS_SITE; |
| CookieSameSiteContextMetadata metadata; |
| CookieSameSiteContextMetadata schemeful_metadata; |
| }; |
| |
| // What rules to apply when determining whether access to a particular cookie is |
| // allowed. |
| // Keep in sync with net/cookies/cookie_constants.h. |
| enum CookieAccessSemantics { |
| UNKNOWN = -1, |
| NONLEGACY = 0, |
| LEGACY, |
| }; |
| |
| // Keep defaults here in sync with net/cookies/cookie_options.cc. |
| struct CookieOptions { |
| bool exclude_httponly = true; |
| CookieSameSiteContext same_site_cookie_context; |
| bool update_access_time = true; |
| bool return_excluded_cookies = false; |
| }; |
| |
| // See net/cookies/canonical_cookie.{h,cc} for documentation. |
| // Keep defaults here in sync with those files. |
| struct CanonicalCookie { |
| string name; |
| string value; |
| string domain; |
| string path; |
| mojo_base.mojom.Time creation; |
| mojo_base.mojom.Time expiry; |
| mojo_base.mojom.Time last_access; |
| mojo_base.mojom.Time last_update; |
| bool secure = false; |
| bool httponly = false; |
| CookieSameSite site_restrictions = NO_RESTRICTION; |
| CookiePriority priority = MEDIUM; |
| CookieSourceScheme source_scheme = kUnset; |
| CookiePartitionKey? partition_key; |
| // -1 because of url::PORT_UNSPECIFIED |
| // url/third_party/mozilla/url_parse.h |
| int32 source_port = -1; |
| CookieSourceType source_type = kUnknown; |
| }; |
| |
| // Indicates reasons why a cookie may be excluded in a get or set |
| // operation and if it should be warned about. |
| // TODO(crbug.com/40219875): Improve serialization validation comments. |
| struct CookieInclusionStatus { |
| // Bitfield. Is defined in |
| // net::CookieInclusionStatus::ExclusionReason. |
| uint32 exclusion_reasons; |
| // Bitfield. Is defined in |
| // net::CookieInclusionStatus::WarningReason. |
| uint32 warning_reasons; |
| |
| CookieExemptionReason exemption_reason; |
| }; |
| |
| struct CookieAndLineWithAccessResult { |
| CanonicalCookie? cookie; |
| string cookie_string; |
| CookieAccessResult access_result; |
| }; |
| |
| union CookieOrLine { |
| CanonicalCookie cookie; |
| string cookie_string; |
| }; |
| |
| struct CookieOrLineWithAccessResult { |
| CookieOrLine cookie_or_line; |
| CookieAccessResult access_result; |
| }; |
| |
| // See net/cookies/cookie_access_result.{cc,h} for documentation. |
| struct CookieAccessResult { |
| CookieEffectiveSameSite effective_same_site; |
| CookieAccessSemantics access_semantics; |
| CookieInclusionStatus status; |
| bool is_allowed_to_access_secure_cookies; |
| }; |
| |
| struct CookieWithAccessResult { |
| CanonicalCookie cookie; |
| CookieAccessResult access_result; |
| }; |
| |
| // Keep values here in sync with net::CookieChangeCause. |
| enum CookieChangeCause { |
| // The cookie was inserted. |
| INSERTED, |
| // The cookie was changed directly by a consumer's action. |
| EXPLICIT, |
| // The cookie was deleted, but no more details are known. |
| UNKNOWN_DELETION, |
| // The cookie was automatically removed due to an insert operation that |
| // overwrote it. |
| OVERWRITE, |
| // The cookie was automatically removed as it expired. |
| EXPIRED, |
| // The cookie was automatically evicted during garbage collection. |
| EVICTED, |
| // The cookie was overwritten with an already-expired expiration date. |
| EXPIRED_OVERWRITE |
| }; |
| |
| struct CookieChangeInfo { |
| // The cookie that changed, in its post-change state. |
| CanonicalCookie cookie; |
| // Access results at the time of the change. |
| CookieAccessResult access_result; |
| CookieChangeCause cause; |
| }; |
| |
| // Session cookies are cookies that expire at the end of the browser session. |
| // That is represented in canonical cookies by a null expiry time. |
| enum CookieDeletionSessionControl { |
| IGNORE_CONTROL, |
| SESSION_COOKIES, |
| PERSISTENT_COOKIES, |
| }; |
| |
| // All existing filters are ANDed together. I.e. if there is a value for |
| // created_after_time and there's a value for including_domains, only cookies |
| // in including_domains that have been created after the specified date would be |
| // deleted. A value for session_control of IGNORE_CONTROL is treated the same |
| // as optional values not being present for the other filters. |
| // If no filters are specified then all cookies will be deleted; this can be |
| // thought of as there being a default "match everything" filter which is |
| // ANDed in with all other filters. |
| // |
| // Note that whether a domain matches a cookie or not is somewhat nuanced. For |
| // the purposes of this filter: |
| // * The host/domain cookie distinction is ignored |
| // * A cookies effective domain is considered to be the top level registry |
| // (including private registries) for the domain stored in the cookie |
| // + the next entry down. So the effective domain for x.y.google.com |
| // would be google.com, and the effective domain for x.google.co.uk would |
| // be google.co.uk. See the function |
| // net::registry_controlled_domains::GetDomainAndRegistry for more |
| // details. |
| // * If a cookie does not have such a top level domain (e.g. IP address |
| // or private hostname), the domain specified in the cookie (the IP |
| // address or private hostname) is used. |
| struct CookieDeletionFilter { |
| // Delete cookies created after a date. |
| mojo_base.mojom.Time? created_after_time; |
| |
| // Delete cookies created before a date. |
| mojo_base.mojom.Time? created_before_time; |
| |
| // Delete cookies whose domains are not listed. |
| array<string>? excluding_domains; |
| |
| // Deletes cookies whose domains are listed. |
| array<string>? including_domains; |
| |
| // Delete cookies with a particular name. |
| string? cookie_name; |
| |
| // Delete cookies from a particular host. |
| string? host_name; |
| |
| // Delete cookies which match the given URL. |
| // See https://tools.ietf.org/html/rfc6265, sections 5.1.{3,4} & 5.2.{5,6} |
| // for matching rules. In general terms, secure cookies only match |
| // https URLs, the domain must match (the cookie domain must be a suffix |
| // of the URL domain), and the path must match (the cookie path must |
| // be a prefix of the URL path). So |
| // a cookie with {domain: ".sub.example.com", path: "/path", secure} |
| // would be deleted if the URL passed was |
| // "https://www.sub.example.com/path/path2" but not if it was |
| // "http://www.example.com/x"--in fact, that cookie wouldn't be deleted |
| // if any of the secure/domain/path attributes in the URL were changed. |
| url.mojom.Url? url; |
| |
| // Delete session/persistent cookies. |
| CookieDeletionSessionControl session_control = IGNORE_CONTROL; |
| |
| // Only delete partitioned cookies contained in this |
| // CookiePartitionKeyCollection. |
| // See net/cookies/cookie_partition_key_collection.h for documentation. |
| // If the field is not set, then we delete cookies from all partitions. This |
| // is equivalent to setting the field to |
| // CookiePartitionKeyCollection::ContainsAll. |
| CookiePartitionKeyCollection? cookie_partition_key_collection; |
| |
| // If true, it indicates that third-party cookie blocking would apply to the |
| // context triggering the deletion. In these cases, we should only delete |
| // partitioned cookies. |
| bool partitioned_state_only; |
| }; |
| |
| interface CookieChangeListener { |
| // TODO(rdsmith): Should this be made a batch interface? |
| OnCookieChange(CookieChangeInfo change); |
| }; |
| |
| // CookieManager is a privileged interface that should only be used in trusted |
| // processes. |
| // |
| // Untrusted processes like renderers should use RestrictedCookieManager. |
| [RequireContext=sandbox.mojom.Context.kBrowser] |
| interface CookieManager { |
| // TODO(rdsmith): Worthwhile specifying a sort order for the getters? |
| |
| // Get all the cookies known to the service. |
| // Returned cookie list is sorted first by path length (longest first) |
| // and second by creation time. |
| // TODO(rdsmith): There are consumers that rely on this behavior, but |
| // for this function it doesn't make a lot of sense not to also sort |
| // on origin. Should the returned cookies also be sorted by origin? |
| GetAllCookies() => (array<CanonicalCookie> cookies); |
| |
| // Get all the cookies known to the service. |
| // Returned cookie list is sorted first by path length (longest first) |
| // and second by creation time. |
| // Additionally get a list of the CookieAccessSemantics that applies to each, |
| // if known. The |access_semantics_list| is guaranteed to be the same length |
| // as |cookies|, with each element in |cookies| having the access semantics |
| // which is given by the same index in |access_semantics_list|. If this method |
| // is not implemented in the underlying CookieStore, the returned |
| // |access_semantics_list| will just contain all UNKNOWNs. If it is |
| // supported, the access semantics values will have been determined by |
| // querying the CookieStore's CookieAccessDelegate. |
| GetAllCookiesWithAccessSemantics() |
| => (array<CanonicalCookie> cookies, |
| array<CookieAccessSemantics> access_semantics_list); |
| |
| // Get all cookies for the specified URL and cookie options. |
| // Will also return any partitioned cookies whose partition key are in |
| // |cookie_partition_key_collection|. |
| // Returned cookie list is sorted first by path length (longest first) |
| // and second by creation time. If the |return_excluded_cookies| option is set |
| // in the options, |excluded_cookies| with be a list of cookies that were |
| // blocked from being sent along with the reason each cookie was blocked. By |
| // default, that option is not set and |excluded_cookies| is an empty list. |
| GetCookieList(url.mojom.Url url, |
| CookieOptions cookie_options, |
| CookiePartitionKeyCollection cookie_partition_key_collection) |
| => (array<CookieWithAccessResult> cookies, |
| array<CookieWithAccessResult> excluded_cookies); |
| |
| // Set a cookie. |source_url| is used to check whether existing secure |
| // cookies can be overwritten (secure cookies may be created from a |
| // non-secure source), and whether the URL's scheme is permitted to use |
| // cookies in the first place. |cookie_options| indicates whether http_only |
| // or SameSite cookies may be overwritten. If a cookie is not permitted to be |
| // set, |status| will indicate why it was blocked. If the cookie is permitted, |
| // |status| will be set to INCLUDE. |
| SetCanonicalCookie(CanonicalCookie cookie, url.mojom.Url source_url, |
| CookieOptions cookie_options) |
| => (CookieAccessResult access_result); |
| |
| // Delete a cookie. Returns true if a cookie was deleted. |
| DeleteCanonicalCookie(CanonicalCookie cookie) => (bool success); |
| |
| // Delete a set of cookies matching the passed filter. |
| // Returns the number of cookies deleted. |
| DeleteCookies(CookieDeletionFilter filter) => (uint32 num_deleted); |
| |
| // Delete cookies marked as session-only in cookie settings. |
| // Returns the number of cookies deleted. |
| DeleteSessionOnlyCookies() => (uint32 num_deleted); |
| |
| // Delete cookies marked as session-only in cookie settings that are stale |
| // (haven't been accessed or updated in 7 days). |
| // Returns the number of cookies deleted. |
| // See crbug.com/40285083 for more info. |
| // |
| // If there is a more general use case for filtering cookie deletion on |
| // the last access time, consider replacing this with a call to DeleteCookies |
| // by adding a last_accessed time range to CookieDeletionFilter. |
| DeleteStaleSessionOnlyCookies() => (uint32 num_deleted); |
| |
| // Subscribes the given listener to changes to a cookie. |
| // |
| // The subscription is canceled by closing the CookieChangeListener's pipe. |
| // |
| // Note that if the caller may be racing with other uses of the cookie store, |
| // it should follow the subscription request with a probe of the relevant |
| // information about the tracked cookie, to make sure that a change to the |
| // cookie did not happen right before the listener was registered. |
| // |
| // If |name| is omitted then changes are returned for all cookies for |url|. |
| // |
| // TODO(rdsmith): Should this have a filter to register for a lot of |
| // notifications at once? Maybe combine with the deletion filter? |
| // TODO(rdsmith): Describe the performance implications of using this method. |
| // The comments in CookieMonster::AddCallbackForCookie look pretty scary. |
| AddCookieChangeListener( |
| url.mojom.Url url, |
| string? name, |
| pending_remote<CookieChangeListener> listener); |
| |
| // Subscribes the given listener to changes to this CookieManager's cookies. |
| // |
| // The subscription is canceled by closing the CookieChangeListener's pipe. |
| // |
| // TODO(rdsmith): Should this have a filter to register for a lot of |
| // notifications at once? Maybe combine with the deletion filter? |
| AddGlobalChangeListener( |
| pending_remote<CookieChangeListener> notification_pointer); |
| |
| // Clone the interface for use somewhere else. After this call, |
| // requests to the same implementation may be posted to the other side |
| // of the pipe new_interface was configured on. |
| [AllowedContext=sandbox.mojom.Context.kBrowser] |
| CloneInterface(pending_receiver<CookieManager> new_interface); |
| |
| // Flush the backing store (if any) to disk. |
| FlushCookieStore() => (); |
| |
| // Configure this CookieManager to allow/disallow setting cookies for file:// |
| // URLs. If this is not called, the CookieManager follows |
| // CookieManagerParams.allow_file_scheme_cookies. This should be called before |
| // the first use of the backing store, otherwise this will have no effect on |
| // the CookieManager, returning false to indicate so. |
| AllowFileSchemeCookies(bool allow) => (bool success); |
| |
| // Sets content settings for cookies. These are used to determine cookie |
| // access and cookie deletion behavior. Will |
| // ack the caller with a callback when settings have been updated. |
| SetContentSettings( |
| content_settings.mojom.ContentSettingsType content_settings_type, |
| array<content_settings.mojom.ContentSettingPatternSource> settings) => (); |
| |
| // Instructs the cookie store to not discard session only cookies on shutdown. |
| SetForceKeepSessionState(); |
| |
| // Enables/Disables blocking of third-party cookies. |
| BlockThirdPartyCookies(bool block); |
| |
| // Enables/Disables mitigations for third-party cookies deprecation. |
| SetMitigationsEnabledFor3pcd(bool enable); |
| |
| // Enables/Disables tracking protection for 3PCD (prefs + UX). |
| SetTrackingProtectionEnabledFor3pcd(bool enable); |
| |
| // Adds a pre-commit delay to the cookie database sqlite persistent store. |
| // This delay occurs before every commit and blocks the background task |
| // runner. |
| SetPreCommitCallbackDelayForTesting(mojo_base.mojom.TimeDelta delay); |
| }; |