1 // Copyright 2013 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_COOKIES_COOKIE_CONSTANTS_H_ 6 #define NET_COOKIES_COOKIE_CONSTANTS_H_ 7 8 #include <string> 9 10 #include "base/time/time.h" 11 #include "net/base/net_export.h" 12 #include "url/gurl.h" 13 14 namespace net { 15 16 // The time threshold for considering a cookie "short-lived" for the purposes of 17 // allowing unsafe methods for unspecified-SameSite cookies defaulted into Lax. 18 NET_EXPORT extern const base::TimeDelta kLaxAllowUnsafeMaxAge; 19 // The short version of the above time threshold, to be used for tests. 20 NET_EXPORT extern const base::TimeDelta kShortLaxAllowUnsafeMaxAge; 21 22 enum CookiePriority { 23 COOKIE_PRIORITY_LOW = 0, 24 COOKIE_PRIORITY_MEDIUM = 1, 25 COOKIE_PRIORITY_HIGH = 2, 26 COOKIE_PRIORITY_DEFAULT = COOKIE_PRIORITY_MEDIUM 27 }; 28 29 // See https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00 30 // and https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis for 31 // information about same site cookie restrictions. 32 // These values are allowed for the SameSite field of a cookie. They mostly 33 // correspond to CookieEffectiveSameSite values. 34 // Note: Don't renumber, as these values are persisted to a database and 35 // recorded to histograms. 36 enum class CookieSameSite { 37 UNSPECIFIED = -1, 38 NO_RESTRICTION = 0, 39 LAX_MODE = 1, 40 STRICT_MODE = 2, 41 // Reserved 3 (was EXTENDED_MODE), next number is 4. 42 43 // Keep last, used for histograms. 44 kMaxValue = STRICT_MODE 45 }; 46 47 // The same as CookieSameSite except that the enums start at 0 to support 48 // standard (non-sparse) enum histograms. Standard enum histograms do not 49 // support negative numbers and while sparse histograms do they have 50 // performance penalties that we want to avoid. 51 enum class CookieSameSiteForMetrics { 52 UNSPECIFIED = 0, 53 NO_RESTRICTION = 1, 54 LAX_MODE = 2, 55 STRICT_MODE = 3, 56 57 // Keep last, used for histograms. 58 kMaxValue = STRICT_MODE 59 }; 60 61 // These are the enforcement modes that may be applied to a cookie when deciding 62 // inclusion/exclusion. They mostly correspond to CookieSameSite values. 63 // Keep in sync with enums.xml. 64 enum class CookieEffectiveSameSite { 65 NO_RESTRICTION = 0, 66 LAX_MODE = 1, 67 STRICT_MODE = 2, 68 LAX_MODE_ALLOW_UNSAFE = 3, 69 // Undefined is used when no value applies for the object as there is no 70 // valid cookie object to evaluate on. 71 UNDEFINED = 4, 72 73 // Keep last, used for histograms. 74 COUNT 75 }; 76 77 // Used for histograms only. Do not renumber. Keep in sync with enums.xml. 78 enum class CookieSameSiteString { 79 // No SameSite attribute is present. 80 kUnspecified = 0, 81 // The SameSite attribute is present but has no value. 82 kEmptyString = 1, 83 // The SameSite attribute has an unrecognized value. 84 kUnrecognized = 2, 85 // The SameSite attribute has a recognized value. 86 kLax = 3, 87 kStrict = 4, 88 kNone = 5, 89 kExtended = 6, // Deprecated, kept for metrics only. 90 91 // Keep last, update if adding new value. 92 kMaxValue = kExtended 93 }; 94 95 // What SameSite rules to apply when determining whether access to a particular 96 // cookie is allowed. 97 // 98 // At present, NONLEGACY semantics enforces the following: 99 // 1) SameSite=Lax by default: A cookie that does not specify a SameSite 100 // attribute will be treated as if it were Lax (except allowing unsafe 101 // top-level requests for 2 minutes after its creation; see 102 // "lax-allowing-unsafe" or "Lax+POST"). 103 // 2) SameSite=None requires Secure: A cookie specifying SameSite=None must 104 // also specify Secure. 105 // 3) Schemeful Same-Site: When determining what requests are considered 106 // same-site or cross-site, a "site" is considered to be a registrable 107 // domain with a scheme (as opposed to just a registrable domain). 108 // 109 // When the semantics is LEGACY, these three behaviors are disabled. When the 110 // semantics is UNKNOWN, the behavior may or may not depend on base::Features. 111 enum class CookieAccessSemantics { 112 // Has not been checked yet or there is no way to check. 113 UNKNOWN = -1, 114 // Has been checked and the cookie should *not* be subject to legacy access 115 // rules. 116 NONLEGACY = 0, 117 // Has been checked and the cookie should be subject to legacy access rules. 118 LEGACY, 119 }; 120 121 // When the Scope is LEGACY, Origin-Bound Cookies behavior are disabled. When 122 // the Scpope is UNKNOWN, the behavior may or may not depend on 123 // base::Features::PortBoundCookies and base::Features::SchemeBoundCookies. 124 enum class CookieLegacyScope { 125 // Has not been checked yet or there is no way to check. 126 UNKNOWN = -1, 127 // Has been checked and the cookie should *not* be subject to legacy scope 128 // rules 129 NONLEGACY = 0, 130 // Has been checked and the cookie should be subject to legacy scope rules 131 LEGACY, 132 }; 133 134 // What scheme was used in the setting of a cookie. 135 // Do not renumber. 136 enum class CookieSourceScheme { 137 kUnset = 0, 138 kNonSecure = 1, 139 kSecure = 2, 140 141 kMaxValue = kSecure // Keep as the last value. 142 }; 143 144 enum class CookiePort { 145 // DO NOT REORDER OR RENUMBER. These are used for histograms. 146 147 // Potentially interesting port values for cookies for use with histograms. 148 149 // Not a port explicitly listed below, including invalid ports (-1, 65536, 150 // etc). 151 kOther = 0, 152 // HTTP 153 k80 = 1, 154 k81 = 2, 155 k82 = 3, 156 k83 = 4, 157 k84 = 5, 158 k85 = 6, 159 // HTTPS 160 k443 = 7, 161 k444 = 8, 162 k445 = 9, 163 k446 = 10, 164 k447 = 11, 165 k448 = 12, 166 // JS Framework 167 k3000 = 13, 168 k3001 = 14, 169 k3002 = 15, 170 k3003 = 16, 171 k3004 = 17, 172 k3005 = 18, 173 // JS Framework 174 k4200 = 19, 175 k4201 = 20, 176 k4202 = 21, 177 k4203 = 22, 178 k4204 = 23, 179 k4205 = 24, 180 // JS Framework 181 k5000 = 25, 182 k5001 = 26, 183 k5002 = 27, 184 k5003 = 28, 185 k5004 = 29, 186 k5005 = 30, 187 // Common Dev Ports 188 k7000 = 31, 189 k7001 = 32, 190 k7002 = 33, 191 k7003 = 34, 192 k7004 = 35, 193 k7005 = 36, 194 // HTTP 195 k8000 = 37, 196 k8001 = 38, 197 k8002 = 39, 198 k8003 = 40, 199 k8004 = 41, 200 k8005 = 42, 201 // HTTP 202 k8080 = 43, 203 k8081 = 44, 204 k8082 = 45, 205 k8083 = 46, 206 k8084 = 47, 207 k8085 = 48, 208 // HTTP 209 k8090 = 49, 210 k8091 = 50, 211 k8092 = 51, 212 k8093 = 52, 213 k8094 = 53, 214 k8095 = 54, 215 // JS Framework 216 k8100 = 55, 217 k8101 = 56, 218 k8102 = 57, 219 k8103 = 58, 220 k8104 = 59, 221 k8105 = 60, 222 // JS Framework 223 k8200 = 61, 224 k8201 = 62, 225 k8202 = 63, 226 k8203 = 64, 227 k8204 = 65, 228 k8205 = 66, 229 // HTTP(S) 230 k8443 = 67, 231 k8444 = 68, 232 k8445 = 69, 233 k8446 = 70, 234 k8447 = 71, 235 k8448 = 72, 236 // HTTP 237 k8888 = 73, 238 k8889 = 74, 239 k8890 = 75, 240 k8891 = 76, 241 k8892 = 77, 242 k8893 = 78, 243 // Common Dev Ports 244 k9000 = 79, 245 k9001 = 80, 246 k9002 = 81, 247 k9003 = 82, 248 k9004 = 83, 249 k9005 = 84, 250 // HTTP 251 k9090 = 85, 252 k9091 = 86, 253 k9092 = 87, 254 k9093 = 88, 255 k9094 = 89, 256 k9095 = 90, 257 258 // Keep as last value. 259 kMaxValue = k9095 260 }; 261 262 // Scheme or trustworthiness used to access or set a cookie. 263 // "potentially trustworthy" here refers to the notion from 264 // https://www.w3.org/TR/powerful-features/#is-origin-trustworthy 265 enum class CookieAccessScheme { 266 // Scheme was non-cryptographic. The non-cryptographic source origin was 267 // either not potentially trustworthy, or its potential 268 // trustworthiness wasn't checked. 269 kNonCryptographic = 0, 270 // Scheme was cryptographic (https or wss). This implies potentially 271 // trustworthy. 272 kCryptographic = 1, 273 // Source was non-cryptographic, but URL was otherwise potentially 274 // trustworthy. 275 kTrustworthy = 2, 276 277 kMaxValue = kTrustworthy // Keep as the last value. 278 }; 279 280 // Used to populate a histogram that measures which schemes are used to set 281 // cookies and how frequently. Many of these probably won't/can't be used, 282 // but we know about them and there's no harm in including them. 283 // 284 // Do not reorder or renumber. Used for metrics. 285 enum class CookieSourceSchemeName { 286 kOther = 0, // Catch all for any other schemes that may be used. 287 kAboutBlankURL = 1, 288 kAboutSrcdocURL = 2, 289 kAboutBlankPath = 3, 290 kAboutSrcdocPath = 4, 291 kAboutScheme = 5, 292 kBlobScheme = 6, 293 kContentScheme = 7, 294 kContentIDScheme = 8, 295 kDataScheme = 9, 296 kFileScheme = 10, 297 kFileSystemScheme = 11, 298 kFtpScheme = 12, 299 kHttpScheme = 13, 300 kHttpsScheme = 14, 301 kJavaScriptScheme = 15, 302 kMailToScheme = 16, 303 kQuicTransportScheme_Obsoleted = 17, 304 kTelScheme = 18, 305 kUrnScheme = 19, 306 kWsScheme = 20, 307 kWssScheme = 21, 308 kChromeExtensionScheme = 22, 309 kMaxValue = kChromeExtensionScheme 310 }; 311 312 // Returns the Set-Cookie header priority token corresponding to |priority|. 313 NET_EXPORT std::string CookiePriorityToString(CookiePriority priority); 314 315 // Converts the Set-Cookie header priority token |priority| to a CookiePriority. 316 // Defaults to COOKIE_PRIORITY_DEFAULT for empty or unrecognized strings. 317 NET_EXPORT CookiePriority StringToCookiePriority(const std::string& priority); 318 319 // Returns a string corresponding to the value of the |same_site| token. 320 // Intended only for debugging/logging. 321 NET_EXPORT std::string CookieSameSiteToString(CookieSameSite same_site); 322 323 // Converts the Set-Cookie header SameSite token |same_site| to a 324 // CookieSameSite. Defaults to CookieSameSite::UNSPECIFIED for empty or 325 // unrecognized strings. Returns an appropriate value of CookieSameSiteString in 326 // |samesite_string| to indicate what type of string was parsed as the SameSite 327 // attribute value, if a pointer is provided. 328 NET_EXPORT CookieSameSite 329 StringToCookieSameSite(const std::string& same_site, 330 CookieSameSiteString* samesite_string = nullptr); 331 332 NET_EXPORT void RecordCookieSameSiteAttributeValueHistogram( 333 CookieSameSiteString value); 334 335 // This function reduces the 65535 available TCP port values down to a <100 336 // potentially interesting values that cookies could be set by or sent to. This 337 // is because UMA cannot handle the full range. 338 NET_EXPORT CookiePort ReducePortRangeForCookieHistogram(const int port); 339 340 // Returns the appropriate enum value for the scheme of the given GURL. 341 CookieSourceSchemeName GetSchemeNameEnum(const GURL& url); 342 343 // This string is used to as a placeholder for the partition_key column in 344 // the SQLite database. All cookies except those set with Partitioned will 345 // have this value in their column. 346 // 347 // Empty string was chosen because it is the smallest, non-null value. 348 NET_EXPORT extern const char kEmptyCookiePartitionKey[]; 349 350 // Enum for measuring usage patterns of CookiesAllowedForUrls. 351 // The policy supports wildcards in the primary or secondary content setting 352 // pattern, and explicit patterns for both. Each variant of this enum represents 353 // policies set with each possible combination of rule types. These values are 354 // persisted to logs. Entries should not be renumbered and numeric values should 355 // never be reused. 356 enum class CookiesAllowedForUrlsUsage { 357 kExplicitOnly = 0, 358 kWildcardPrimaryOnly = 1, 359 kWildcardSecondaryOnly = 2, 360 kExplicitAndPrimaryWildcard = 3, 361 kExplicitAndSecondaryWildcard = 4, 362 kWildcardOnly = 5, 363 kAllPresent = 6, 364 365 kMaxValue = kAllPresent, 366 }; 367 368 // Possible values for the 'source_type' column. 369 // 370 // Do not reorder or renumber. Used for metrics. 371 enum class CookieSourceType { 372 // 'unknown' is used for tests or cookies set before this field was added. 373 kUnknown = 0, 374 // 'http' is used for cookies set via HTTP Response Headers. 375 kHTTP = 1, 376 // 'script' is used for cookies set via document.cookie. 377 kScript = 2, 378 // 'other' is used for cookies set via browser login, iOS, WebView APIs, 379 // Extension APIs, or DevTools. 380 kOther = 3, 381 382 kMaxValue = kOther, // Keep as the last value. 383 }; 384 385 // The special cookie prefixes as defined in 386 // https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-13#name-cookie-name-prefixes 387 // 388 // This enum is being histogrammed; do not reorder or remove values. 389 enum CookiePrefix { 390 COOKIE_PREFIX_NONE = 0, 391 COOKIE_PREFIX_SECURE, 392 COOKIE_PREFIX_HOST, 393 COOKIE_PREFIX_LAST 394 }; 395 396 } // namespace net 397 398 #endif // NET_COOKIES_COOKIE_CONSTANTS_H_ 399