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 // What scheme was used in the setting of a cookie. 122 // Do not renumber. 123 enum class CookieSourceScheme { 124 kUnset = 0, 125 kNonSecure = 1, 126 kSecure = 2, 127 128 kMaxValue = kSecure // Keep as the last value. 129 }; 130 131 enum class CookiePort { 132 // DO NOT REORDER OR RENUMBER. These are used for histograms. 133 134 // Potentially interesting port values for cookies for use with histograms. 135 136 // Not a port explicitly listed below, including invalid ports (-1, 65536, 137 // etc). 138 kOther = 0, 139 // HTTP 140 k80 = 1, 141 k81 = 2, 142 k82 = 3, 143 k83 = 4, 144 k84 = 5, 145 k85 = 6, 146 // HTTPS 147 k443 = 7, 148 k444 = 8, 149 k445 = 9, 150 k446 = 10, 151 k447 = 11, 152 k448 = 12, 153 // JS Framework 154 k3000 = 13, 155 k3001 = 14, 156 k3002 = 15, 157 k3003 = 16, 158 k3004 = 17, 159 k3005 = 18, 160 // JS Framework 161 k4200 = 19, 162 k4201 = 20, 163 k4202 = 21, 164 k4203 = 22, 165 k4204 = 23, 166 k4205 = 24, 167 // JS Framework 168 k5000 = 25, 169 k5001 = 26, 170 k5002 = 27, 171 k5003 = 28, 172 k5004 = 29, 173 k5005 = 30, 174 // Common Dev Ports 175 k7000 = 31, 176 k7001 = 32, 177 k7002 = 33, 178 k7003 = 34, 179 k7004 = 35, 180 k7005 = 36, 181 // HTTP 182 k8000 = 37, 183 k8001 = 38, 184 k8002 = 39, 185 k8003 = 40, 186 k8004 = 41, 187 k8005 = 42, 188 // HTTP 189 k8080 = 43, 190 k8081 = 44, 191 k8082 = 45, 192 k8083 = 46, 193 k8084 = 47, 194 k8085 = 48, 195 // HTTP 196 k8090 = 49, 197 k8091 = 50, 198 k8092 = 51, 199 k8093 = 52, 200 k8094 = 53, 201 k8095 = 54, 202 // JS Framework 203 k8100 = 55, 204 k8101 = 56, 205 k8102 = 57, 206 k8103 = 58, 207 k8104 = 59, 208 k8105 = 60, 209 // JS Framework 210 k8200 = 61, 211 k8201 = 62, 212 k8202 = 63, 213 k8203 = 64, 214 k8204 = 65, 215 k8205 = 66, 216 // HTTP(S) 217 k8443 = 67, 218 k8444 = 68, 219 k8445 = 69, 220 k8446 = 70, 221 k8447 = 71, 222 k8448 = 72, 223 // HTTP 224 k8888 = 73, 225 k8889 = 74, 226 k8890 = 75, 227 k8891 = 76, 228 k8892 = 77, 229 k8893 = 78, 230 // Common Dev Ports 231 k9000 = 79, 232 k9001 = 80, 233 k9002 = 81, 234 k9003 = 82, 235 k9004 = 83, 236 k9005 = 84, 237 // HTTP 238 k9090 = 85, 239 k9091 = 86, 240 k9092 = 87, 241 k9093 = 88, 242 k9094 = 89, 243 k9095 = 90, 244 245 // Keep as last value. 246 kMaxValue = k9095 247 }; 248 249 // Scheme or trustworthiness used to access or set a cookie. 250 // "potentially trustworthy" here refers to the notion from 251 // https://www.w3.org/TR/powerful-features/#is-origin-trustworthy 252 enum class CookieAccessScheme { 253 // Scheme was non-cryptographic. The non-cryptographic source origin was 254 // either not potentially trustworthy, or its potential 255 // trustworthiness wasn't checked. 256 kNonCryptographic = 0, 257 // Scheme was cryptographic (https or wss). This implies potentially 258 // trustworthy. 259 kCryptographic = 1, 260 // Source was non-cryptographic, but URL was otherwise potentially 261 // trustworthy. 262 kTrustworthy = 2, 263 264 kMaxValue = kTrustworthy // Keep as the last value. 265 }; 266 267 // Used to populate a histogram that measures which schemes are used to set 268 // cookies and how frequently. Many of these probably won't/can't be used, 269 // but we know about them and there's no harm in including them. 270 // 271 // Do not reorder or renumber. Used for metrics. 272 enum class CookieSourceSchemeName { 273 kOther = 0, // Catch all for any other schemes that may be used. 274 kAboutBlankURL = 1, 275 kAboutSrcdocURL = 2, 276 kAboutBlankPath = 3, 277 kAboutSrcdocPath = 4, 278 kAboutScheme = 5, 279 kBlobScheme = 6, 280 kContentScheme = 7, 281 kContentIDScheme = 8, 282 kDataScheme = 9, 283 kFileScheme = 10, 284 kFileSystemScheme = 11, 285 kFtpScheme = 12, 286 kHttpScheme = 13, 287 kHttpsScheme = 14, 288 kJavaScriptScheme = 15, 289 kMailToScheme = 16, 290 kQuicTransportScheme_Obsoleted = 17, 291 kTelScheme = 18, 292 kUrnScheme = 19, 293 kWsScheme = 20, 294 kWssScheme = 21, 295 kChromeExtensionScheme = 22, 296 kMaxValue = kChromeExtensionScheme 297 }; 298 299 // Returns the Set-Cookie header priority token corresponding to |priority|. 300 NET_EXPORT std::string CookiePriorityToString(CookiePriority priority); 301 302 // Converts the Set-Cookie header priority token |priority| to a CookiePriority. 303 // Defaults to COOKIE_PRIORITY_DEFAULT for empty or unrecognized strings. 304 NET_EXPORT CookiePriority StringToCookiePriority(const std::string& priority); 305 306 // Returns a string corresponding to the value of the |same_site| token. 307 // Intended only for debugging/logging. 308 NET_EXPORT std::string CookieSameSiteToString(CookieSameSite same_site); 309 310 // Converts the Set-Cookie header SameSite token |same_site| to a 311 // CookieSameSite. Defaults to CookieSameSite::UNSPECIFIED for empty or 312 // unrecognized strings. Returns an appropriate value of CookieSameSiteString in 313 // |samesite_string| to indicate what type of string was parsed as the SameSite 314 // attribute value, if a pointer is provided. 315 NET_EXPORT CookieSameSite 316 StringToCookieSameSite(const std::string& same_site, 317 CookieSameSiteString* samesite_string = nullptr); 318 319 NET_EXPORT void RecordCookieSameSiteAttributeValueHistogram( 320 CookieSameSiteString value); 321 322 // This function reduces the 65535 available TCP port values down to a <100 323 // potentially interesting values that cookies could be set by or sent to. This 324 // is because UMA cannot handle the full range. 325 NET_EXPORT CookiePort ReducePortRangeForCookieHistogram(const int port); 326 327 // Returns the appropriate enum value for the scheme of the given GURL. 328 CookieSourceSchemeName GetSchemeNameEnum(const GURL& url); 329 330 // This string is used to as a placeholder for the partition_key column in 331 // the SQLite database. All cookies except those set with Partitioned will 332 // have this value in their column. 333 // 334 // Empty string was chosen because it is the smallest, non-null value. 335 NET_EXPORT extern const char kEmptyCookiePartitionKey[]; 336 337 // Used for a histogram that measures which character caused the cookie 338 // string to be truncated. 339 // 340 // Do not reorder or renumber. Used for metrics. 341 enum class TruncatingCharacterInCookieStringType { 342 // No truncating character in the cookie line. 343 kTruncatingCharNone = 0, 344 // Cookie line truncated because of \x0. 345 kTruncatingCharNull = 1, 346 // Cookie line truncated because of \xD. 347 kTruncatingCharNewline = 2, 348 // Cookie line truncated because of \xA. 349 kTruncatingCharLineFeed = 3, 350 351 kMaxValue = kTruncatingCharLineFeed, // Keep as the last value. 352 }; 353 354 // Enum for measuring usage patterns of CookiesAllowedForUrls. 355 // The policy supports wildcards in the primary or secondary content setting 356 // pattern, and explicit patterns for both. Each variant of this enum represents 357 // policies set with each possible combination of rule types. These values are 358 // persisted to logs. Entries should not be renumbered and numeric values should 359 // never be reused. 360 enum class CookiesAllowedForUrlsUsage { 361 kExplicitOnly = 0, 362 kWildcardPrimaryOnly = 1, 363 kWildcardSecondaryOnly = 2, 364 kExplicitAndPrimaryWildcard = 3, 365 kExplicitAndSecondaryWildcard = 4, 366 kWildcardOnly = 5, 367 kAllPresent = 6, 368 369 kMaxValue = kAllPresent, 370 }; 371 372 // Possible values for the 'source_type' column. 373 // 374 // Do not reorder or renumber. Used for metrics. 375 enum class CookieSourceType { 376 // 'unknown' is used for tests or cookies set before this field was added. 377 kUnknown = 0, 378 // 'http' is used for cookies set via HTTP Response Headers. 379 kHTTP = 1, 380 // 'script' is used for cookies set via document.cookie. 381 kScript = 2, 382 // 'other' is used for cookies set via browser login, iOS, WebView APIs, 383 // Extension APIs, or DevTools. 384 kOther = 3, 385 386 kMaxValue = kOther, // Keep as the last value. 387 }; 388 389 } // namespace net 390 391 #endif // NET_COOKIES_COOKIE_CONSTANTS_H_ 392