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