cookie_constants.h | Explore in Territory

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

#ifndef NET_COOKIES_COOKIE_CONSTANTS_H_
#define NET_COOKIES_COOKIE_CONSTANTS_H_

#include <string>

#include "base/time/time.h"
#include "net/base/net_export.h"
#include "url/gurl.h"

namespace net {

// The time threshold for considering a cookie "short-lived" for the purposes of
// allowing unsafe methods for unspecified-SameSite cookies defaulted into Lax.
NET_EXPORT extern const base::TimeDelta kLaxAllowUnsafeMaxAge;
// The short version of the above time threshold, to be used for tests.
NET_EXPORT extern const base::TimeDelta kShortLaxAllowUnsafeMaxAge;

enum CookiePriority { … };

// 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.
// These values are allowed for the SameSite field of a cookie. They mostly
// correspond to CookieEffectiveSameSite values.
// Note: Don't renumber, as these values are persisted to a database and
// recorded to histograms.
enum class CookieSameSite { … };

// The same as CookieSameSite except that the enums start at 0 to support
// standard (non-sparse) enum histograms. Standard enum histograms do not
// support negative numbers and while sparse histograms do they have
// performance penalties that we want to avoid.
enum class CookieSameSiteForMetrics { … };

// These are the enforcement modes that may be applied to a cookie when deciding
// inclusion/exclusion. They mostly correspond to CookieSameSite values.
// Keep in sync with enums.xml.
enum class CookieEffectiveSameSite { … };

// Used for histograms only. Do not renumber. Keep in sync with enums.xml.
enum class CookieSameSiteString { … };

// What SameSite rules to apply when determining whether access to a particular
// cookie is allowed.
//
// At present, NONLEGACY semantics enforces the following:
//  1) SameSite=Lax by default: A cookie that does not specify a SameSite
//     attribute will be treated as if it were Lax (except allowing unsafe
//     top-level requests for 2 minutes after its creation; see
//     "lax-allowing-unsafe" or "Lax+POST").
//  2) SameSite=None requires Secure: A cookie specifying SameSite=None must
//     also specify Secure.
//  3) Schemeful Same-Site: When determining what requests are considered
//     same-site or cross-site, a "site" is considered to be a registrable
//     domain with a scheme (as opposed to just a registrable domain).
//
// When the semantics is LEGACY, these three behaviors are disabled. When the
// semantics is UNKNOWN, the behavior may or may not depend on base::Features.
enum class CookieAccessSemantics { … };

// What scheme was used in the setting of a cookie.
// Do not renumber.
enum class CookieSourceScheme { … };

enum class CookiePort { … };

// Scheme or trustworthiness used to access or set a cookie.
// "potentially trustworthy" here refers to the notion from
// https://www.w3.org/TR/powerful-features/#is-origin-trustworthy
enum class CookieAccessScheme { … };

// Used to populate a histogram that measures which schemes are used to set
// cookies and how frequently. Many of these probably won't/can't be used,
// but we know about them and there's no harm in including them.
//
// Do not reorder or renumber. Used for metrics.
enum class CookieSourceSchemeName { … };

// Returns the Set-Cookie header priority token corresponding to |priority|.
NET_EXPORT std::string CookiePriorityToString(CookiePriority priority);

// Converts the Set-Cookie header priority token |priority| to a CookiePriority.
// Defaults to COOKIE_PRIORITY_DEFAULT for empty or unrecognized strings.
NET_EXPORT CookiePriority StringToCookiePriority(const std::string& priority);

// Returns a string corresponding to the value of the |same_site| token.
// Intended only for debugging/logging.
NET_EXPORT std::string CookieSameSiteToString(CookieSameSite same_site);

// Converts the Set-Cookie header SameSite token |same_site| to a
// CookieSameSite. Defaults to CookieSameSite::UNSPECIFIED for empty or
// unrecognized strings. Returns an appropriate value of CookieSameSiteString in
// |samesite_string| to indicate what type of string was parsed as the SameSite
// attribute value, if a pointer is provided.
NET_EXPORT CookieSameSite
StringToCookieSameSite(const std::string& same_site,
                       CookieSameSiteString* samesite_string = nullptr);

NET_EXPORT void RecordCookieSameSiteAttributeValueHistogram(
    CookieSameSiteString value);

// This function reduces the 65535 available TCP port values down to a <100
// potentially interesting values that cookies could be set by or sent to. This
// is because UMA cannot handle the full range.
NET_EXPORT CookiePort ReducePortRangeForCookieHistogram(const int port);

// Returns the appropriate enum value for the scheme of the given GURL.
CookieSourceSchemeName GetSchemeNameEnum(const GURL& url);

// This string is used to as a placeholder for the partition_key column in
// the SQLite database. All cookies except those set with Partitioned will
// have this value in their column.
//
// Empty string was chosen because it is the smallest, non-null value.
NET_EXPORT extern const char kEmptyCookiePartitionKey[];

// Enum for measuring usage patterns of CookiesAllowedForUrls.
// The policy supports wildcards in the primary or secondary content setting
// pattern, and explicit patterns for both. Each variant of this enum represents
// policies set with each possible combination of rule types. These values are
// persisted to logs. Entries should not be renumbered and numeric values should
// never be reused.
enum class CookiesAllowedForUrlsUsage { … };

// Possible values for the 'source_type' column.
//
// Do not reorder or renumber. Used for metrics.
enum class CookieSourceType { … };

// The special cookie prefixes as defined in
// https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#name-cookie-name-prefixes
//
// This enum is being histogrammed; do not reorder or remove values.
enum CookiePrefix { … };

}  // namespace net

#endif  // NET_COOKIES_COOKIE_CONSTANTS_H_
chromium/net/cookies/cookie_constants.h
