cookie_constants.h 11 KB

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