cookie_options.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333
  1. // Copyright (c) 2012 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. // Brought to you by number 42.
  5. #ifndef NET_COOKIES_COOKIE_OPTIONS_H_
  6. #define NET_COOKIES_COOKIE_OPTIONS_H_
  7. #include <ostream>
  8. #include "net/base/net_export.h"
  9. #include "net/cookies/cookie_constants.h"
  10. #include "net/cookies/cookie_inclusion_status.h"
  11. #include "net/cookies/same_party_context.h"
  12. #include "url/gurl.h"
  13. namespace net {
  14. class NET_EXPORT CookieOptions {
  15. public:
  16. // Relation between the cookie and the navigational environment.
  17. class NET_EXPORT SameSiteCookieContext {
  18. public:
  19. // CROSS_SITE to SAME_SITE_STRICT are ordered from least to most trusted
  20. // environment. Don't renumber, used in histograms.
  21. enum class ContextType {
  22. CROSS_SITE = 0,
  23. // Same rules as lax but the http method is unsafe.
  24. SAME_SITE_LAX_METHOD_UNSAFE = 1,
  25. SAME_SITE_LAX = 2,
  26. SAME_SITE_STRICT = 3,
  27. // Keep last, used for histograms.
  28. COUNT
  29. };
  30. // Holds metadata about the factors that went into deciding the ContextType.
  31. //
  32. // These values may be used for recording histograms or
  33. // CookieInclusionStatus warnings, but SHOULD NOT be relied
  34. // upon for cookie inclusion decisions. Use only the ContextTypes for that.
  35. //
  36. // When adding a field, also update CompleteEquivalenceForTesting.
  37. struct NET_EXPORT ContextMetadata {
  38. // Possible "downgrades" for the SameSite context type, e.g. from a more
  39. // trusted context to a less trusted context, as a result of some behavior
  40. // change affecting the same-site calculation.
  41. enum class ContextDowngradeType {
  42. // Context not downgraded.
  43. kNoDowngrade,
  44. // Context was originally strictly same-site, was downgraded to laxly
  45. // same-site.
  46. kStrictToLax,
  47. // Context was originally strictly same-site, was downgraded to
  48. // cross-site.
  49. kStrictToCross,
  50. // Context was originally laxly same-site, was downgraded to cross-site.
  51. kLaxToCross,
  52. };
  53. // These values are persisted to logs. Entries should not be renumbered
  54. // and numeric values should never be reused.
  55. // This enum is to help collect metrics for https://crbug.com/1221316.
  56. // Specifically it's to help indicate how many cookies are accessed with a
  57. // given redirect type in order to provide a denominator for the
  58. // Cookie.CrossSiteRedirectDowngradeChangesInclusion2.* metrics.
  59. // Note: for this enum the notation A->B->C means that a navigation from
  60. // A to B was redirected to C. I.e.: A is the initator of the navigation
  61. // and C is the final url.
  62. enum class ContextRedirectTypeBug1221316 {
  63. kUnset =
  64. 0, // Indicates this value was unused and shouldn't be read. E.x.:
  65. // A javascript access means this value is meaningless.
  66. kNoRedirect = 1, // There weren't any redirects. E.x.: A->B, A->A
  67. kCrossSiteRedirect =
  68. 2, // There was a redirect but it didn't start and
  69. // end at the same site or the redirect was to a different site
  70. // than the site-for-cookies. E.x.: A->B->C or B->B->B when the
  71. // site-for-cookies is A.
  72. kPartialSameSiteRedirect =
  73. 3, // There was a redirect and the start and
  74. // end are the same site. E.x.: A->B->A. Only this one could
  75. // potentially set cross_site_redirect_downgrade.
  76. kAllSameSiteRedirect = 4, // There was a redirect and all urls are the
  77. // same site. E.x.:, A->A->A
  78. kMaxValue = kAllSameSiteRedirect
  79. };
  80. // Records the type of any context downgrade due to a cross-site redirect,
  81. // i.e. whether the spec change in
  82. // https://github.com/httpwg/http-extensions/pull/1348 changed the result
  83. // of the context calculation. Note that a lax-to-cross downgrade can only
  84. // happen for response cookies, because a laxly same-site context only
  85. // happens for a top-level cross-site request, which cannot be downgraded
  86. // due to a cross-site redirect to a non-top-level cross-site request.
  87. // This only records whether the context was downgraded, not whether the
  88. // cookie's inclusion result was changed.
  89. ContextDowngradeType cross_site_redirect_downgrade =
  90. ContextDowngradeType::kNoDowngrade;
  91. ContextRedirectTypeBug1221316 redirect_type_bug_1221316 =
  92. ContextRedirectTypeBug1221316::kUnset;
  93. };
  94. // The following three constructors apply default values for the metadata
  95. // members.
  96. SameSiteCookieContext()
  97. : SameSiteCookieContext(ContextType::CROSS_SITE,
  98. ContextType::CROSS_SITE) {}
  99. explicit SameSiteCookieContext(ContextType same_site_context)
  100. : SameSiteCookieContext(same_site_context, same_site_context) {}
  101. SameSiteCookieContext(ContextType same_site_context,
  102. ContextType schemeful_same_site_context)
  103. : SameSiteCookieContext(same_site_context,
  104. schemeful_same_site_context,
  105. ContextMetadata(),
  106. ContextMetadata()) {}
  107. // Schemeful and schemeless context types are consistency-checked against
  108. // each other, but the metadata is stored as-is (i.e. the values in
  109. // `metadata` and `schemeful_metadata` may be logically inconsistent), as
  110. // the metadata is not relied upon for correctness.
  111. SameSiteCookieContext(ContextType same_site_context,
  112. ContextType schemeful_same_site_context,
  113. ContextMetadata metadata,
  114. ContextMetadata schemeful_metadata)
  115. : context_(same_site_context),
  116. schemeful_context_(schemeful_same_site_context),
  117. metadata_(metadata),
  118. schemeful_metadata_(schemeful_metadata) {
  119. DCHECK_LE(schemeful_context_, context_);
  120. }
  121. // Convenience method which returns a SameSiteCookieContext with the most
  122. // inclusive contexts. This allows access to all SameSite cookies.
  123. static SameSiteCookieContext MakeInclusive();
  124. // Convenience method which returns a SameSiteCookieContext with the most
  125. // inclusive contexts for set. This allows setting all SameSite cookies.
  126. static SameSiteCookieContext MakeInclusiveForSet();
  127. // Returns the context for determining SameSite cookie inclusion.
  128. ContextType GetContextForCookieInclusion() const;
  129. // Returns the metadata describing how this context was calculated, under
  130. // the currently applicable schemeful/schemeless mode.
  131. // TODO(chlily): Should take the CookieAccessSemantics as well, to
  132. // accurately account for the context actually used for a given cookie.
  133. const ContextMetadata& GetMetadataForCurrentSchemefulMode() const;
  134. // If you're just trying to determine if a cookie is accessible you likely
  135. // want to use GetContextForCookieInclusion() which will return the correct
  136. // context regardless the status of same-site features.
  137. ContextType context() const { return context_; }
  138. ContextType schemeful_context() const { return schemeful_context_; }
  139. // You probably want to use GetMetadataForCurrentSchemefulMode() instead of
  140. // these getters, since that takes into account the applicable schemeful
  141. // mode.
  142. const ContextMetadata& metadata() const { return metadata_; }
  143. ContextMetadata& metadata() { return metadata_; }
  144. const ContextMetadata& schemeful_metadata() const {
  145. return schemeful_metadata_;
  146. }
  147. ContextMetadata& schemeful_metadata() { return schemeful_metadata_; }
  148. // Sets context types. Does not check for consistency between context and
  149. // schemeful context. Does not touch the metadata.
  150. void SetContextTypesForTesting(ContextType context_type,
  151. ContextType schemeful_context_type);
  152. // Returns whether the context types and all fields of the metadata structs
  153. // are the same.
  154. bool CompleteEquivalenceForTesting(
  155. const SameSiteCookieContext& other) const;
  156. // Equality operators disregard any metadata! (Only the context types are
  157. // compared, not how they were computed.)
  158. NET_EXPORT friend bool operator==(
  159. const CookieOptions::SameSiteCookieContext& lhs,
  160. const CookieOptions::SameSiteCookieContext& rhs);
  161. NET_EXPORT friend bool operator!=(
  162. const CookieOptions::SameSiteCookieContext& lhs,
  163. const CookieOptions::SameSiteCookieContext& rhs);
  164. private:
  165. ContextType context_;
  166. ContextType schemeful_context_;
  167. ContextMetadata metadata_;
  168. ContextMetadata schemeful_metadata_;
  169. };
  170. // Creates a CookieOptions object which:
  171. //
  172. // * Excludes HttpOnly cookies
  173. // * Excludes SameSite cookies
  174. // * Updates last-accessed time.
  175. // * Does not report excluded cookies in APIs that can do so.
  176. // * Excludes SameParty cookies.
  177. //
  178. // These settings can be altered by calling:
  179. //
  180. // * |set_{include,exclude}_httponly()|
  181. // * |set_same_site_cookie_context()|
  182. // * |set_do_not_update_access_time()|
  183. // * |set_same_party_cookie_context_type()|
  184. CookieOptions();
  185. CookieOptions(const CookieOptions& other);
  186. CookieOptions(CookieOptions&& other);
  187. ~CookieOptions();
  188. CookieOptions& operator=(const CookieOptions&);
  189. CookieOptions& operator=(CookieOptions&&);
  190. void set_exclude_httponly() { exclude_httponly_ = true; }
  191. void set_include_httponly() { exclude_httponly_ = false; }
  192. bool exclude_httponly() const { return exclude_httponly_; }
  193. // How trusted is the current browser environment when it comes to accessing
  194. // SameSite cookies. Default is not trusted, e.g. CROSS_SITE.
  195. void set_same_site_cookie_context(const SameSiteCookieContext& context) {
  196. same_site_cookie_context_ = context;
  197. }
  198. const SameSiteCookieContext& same_site_cookie_context() const {
  199. return same_site_cookie_context_;
  200. }
  201. void set_update_access_time() { update_access_time_ = true; }
  202. void set_do_not_update_access_time() { update_access_time_ = false; }
  203. bool update_access_time() const { return update_access_time_; }
  204. void set_return_excluded_cookies() { return_excluded_cookies_ = true; }
  205. void unset_return_excluded_cookies() { return_excluded_cookies_ = false; }
  206. bool return_excluded_cookies() const { return return_excluded_cookies_; }
  207. void set_same_party_context(const SamePartyContext& context) {
  208. same_party_context_ = context;
  209. }
  210. const SamePartyContext& same_party_context() const {
  211. return same_party_context_;
  212. }
  213. // Getter/setter of |full_party_context_size_| for logging purposes.
  214. void set_full_party_context_size(uint32_t len) {
  215. full_party_context_size_ = len;
  216. }
  217. uint32_t full_party_context_size() const { return full_party_context_size_; }
  218. void set_is_in_nontrivial_first_party_set(bool is_member) {
  219. is_in_nontrivial_first_party_set_ = is_member;
  220. }
  221. bool is_in_nontrivial_first_party_set() const {
  222. return is_in_nontrivial_first_party_set_;
  223. }
  224. // Convenience method for where you need a CookieOptions that will
  225. // work for getting/setting all types of cookies, including HttpOnly and
  226. // SameSite cookies. Also specifies not to update the access time, because
  227. // usually this is done to get all the cookies to check that they are correct,
  228. // including the creation time. This basically makes a CookieOptions that is
  229. // the opposite of the default CookieOptions.
  230. static CookieOptions MakeAllInclusive();
  231. private:
  232. // Keep default values in sync with
  233. // content/public/common/cookie_manager.mojom.
  234. bool exclude_httponly_ = true;
  235. SameSiteCookieContext same_site_cookie_context_;
  236. bool update_access_time_ = true;
  237. bool return_excluded_cookies_ = false;
  238. SamePartyContext same_party_context_;
  239. // The size of the isolation_info.party_context plus the top-frame site.
  240. // Stored for logging purposes.
  241. uint32_t full_party_context_size_ = 0;
  242. // Whether the site requesting cookie access (as opposed to e.g. the
  243. // `site_for_cookies`) is a member (or owner) of a nontrivial First-Party
  244. // Set.
  245. // This is included here temporarily, for the purpose of ignoring SameParty
  246. // for sites that are not participating in the Origin Trial.
  247. // TODO(https://crbug.com/1163990): remove this field.
  248. bool is_in_nontrivial_first_party_set_ = false;
  249. };
  250. NET_EXPORT bool operator==(
  251. const CookieOptions::SameSiteCookieContext::ContextMetadata& lhs,
  252. const CookieOptions::SameSiteCookieContext::ContextMetadata& rhs);
  253. NET_EXPORT bool operator!=(
  254. const CookieOptions::SameSiteCookieContext::ContextMetadata& lhs,
  255. const CookieOptions::SameSiteCookieContext::ContextMetadata& rhs);
  256. // Allows gtest to print more helpful error messages instead of printing hex.
  257. // (No need to null-check `os` because we can assume gtest will properly pass a
  258. // non-null pointer, and it is dereferenced immediately anyway.)
  259. inline void PrintTo(CookieOptions::SameSiteCookieContext::ContextType ct,
  260. std::ostream* os) {
  261. *os << static_cast<int>(ct);
  262. }
  263. inline void PrintTo(
  264. const CookieOptions::SameSiteCookieContext::ContextMetadata& m,
  265. std::ostream* os) {
  266. *os << "{";
  267. *os << " cross_site_redirect_downgrade: "
  268. << static_cast<int>(m.cross_site_redirect_downgrade);
  269. *os << ", redirect_type_bug_1221316: "
  270. << static_cast<int>(m.redirect_type_bug_1221316);
  271. *os << " }";
  272. }
  273. inline void PrintTo(const CookieOptions::SameSiteCookieContext& sscc,
  274. std::ostream* os) {
  275. *os << "{ context: ";
  276. PrintTo(sscc.context(), os);
  277. *os << ", schemeful_context: ";
  278. PrintTo(sscc.schemeful_context(), os);
  279. *os << ", metadata: ";
  280. PrintTo(sscc.metadata(), os);
  281. *os << ", schemeful_metadata: ";
  282. PrintTo(sscc.schemeful_metadata(), os);
  283. *os << " }";
  284. }
  285. } // namespace net
  286. #endif // NET_COOKIES_COOKIE_OPTIONS_H_