network_isolation_key.h 6.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170
  1. // Copyright 2019 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_BASE_NETWORK_ISOLATION_KEY_H_
  5. #define NET_BASE_NETWORK_ISOLATION_KEY_H_
  6. #include <string>
  7. #include "base/gtest_prod_util.h"
  8. #include "base/unguessable_token.h"
  9. #include "net/base/net_export.h"
  10. #include "net/base/schemeful_site.h"
  11. #include "third_party/abseil-cpp/absl/types/optional.h"
  12. namespace base {
  13. class Value;
  14. }
  15. namespace url {
  16. class Origin;
  17. }
  18. namespace net {
  19. // Key used to isolate shared network stack resources used by requests based on
  20. // the context on which they were made.
  21. class NET_EXPORT NetworkIsolationKey {
  22. public:
  23. // Full constructor. When a request is initiated by the top frame, it must
  24. // also populate the |frame_site| parameter when calling this constructor.
  25. NetworkIsolationKey(const SchemefulSite& top_frame_site,
  26. const SchemefulSite& frame_site,
  27. const base::UnguessableToken* nonce = nullptr);
  28. // Alternative constructor that takes ownership of arguments, to save copies.
  29. NetworkIsolationKey(SchemefulSite&& top_frame_site,
  30. SchemefulSite&& frame_site,
  31. const base::UnguessableToken* nonce = nullptr);
  32. // Legacy constructor.
  33. // TODO(https://crbug.com/1145294): Remove this in favor of above
  34. // constructor.
  35. NetworkIsolationKey(const url::Origin& top_frame_origin,
  36. const url::Origin& frame_origin);
  37. // Construct an empty key.
  38. NetworkIsolationKey();
  39. NetworkIsolationKey(const NetworkIsolationKey& network_isolation_key);
  40. NetworkIsolationKey(NetworkIsolationKey&& network_isolation_key);
  41. ~NetworkIsolationKey();
  42. NetworkIsolationKey& operator=(
  43. const NetworkIsolationKey& network_isolation_key);
  44. NetworkIsolationKey& operator=(NetworkIsolationKey&& network_isolation_key);
  45. // Creates a transient non-empty NetworkIsolationKey by creating an opaque
  46. // origin. This prevents the NetworkIsolationKey from sharing data with other
  47. // NetworkIsolationKeys. Data for transient NetworkIsolationKeys is not
  48. // persisted to disk.
  49. static NetworkIsolationKey CreateTransient();
  50. // Creates a new key using |top_frame_site_| and |new_frame_site|.
  51. NetworkIsolationKey CreateWithNewFrameSite(
  52. const SchemefulSite& new_frame_site) const;
  53. // Intended for temporary use in locations that should be using main frame and
  54. // frame origin, but are currently only using frame origin, because the
  55. // creating object may be shared across main frame objects. Having a special
  56. // constructor for these methods makes it easier to keep track of locating
  57. // callsites that need to have their NetworkIsolationKey filled in.
  58. static NetworkIsolationKey ToDoUseTopFrameOriginAsWell(
  59. const url::Origin& incorrectly_used_frame_origin) {
  60. return NetworkIsolationKey(incorrectly_used_frame_origin,
  61. incorrectly_used_frame_origin);
  62. }
  63. // Compare keys for equality, true if all enabled fields are equal.
  64. bool operator==(const NetworkIsolationKey& other) const {
  65. return std::tie(top_frame_site_, frame_site_, nonce_) ==
  66. std::tie(other.top_frame_site_, other.frame_site_, other.nonce_);
  67. }
  68. // Compare keys for inequality, true if any enabled field varies.
  69. bool operator!=(const NetworkIsolationKey& other) const {
  70. return !(*this == other);
  71. }
  72. // Provide an ordering for keys based on all enabled fields.
  73. bool operator<(const NetworkIsolationKey& other) const {
  74. return std::tie(top_frame_site_, frame_site_, nonce_) <
  75. std::tie(other.top_frame_site_, other.frame_site_, other.nonce_);
  76. }
  77. // Returns the string representation of the key for use in string-keyed disk
  78. // cache. This is the string representation of each piece of the key separated
  79. // by spaces. Returns nullopt if the network isolation key is transient, in
  80. // which case, nothing should typically be saved to disk using the key.
  81. absl::optional<std::string> ToCacheKeyString() const;
  82. // Returns string for debugging. Difference from ToString() is that transient
  83. // entries may be distinguishable from each other.
  84. std::string ToDebugString() const;
  85. // Returns true if all parts of the key are non-empty.
  86. bool IsFullyPopulated() const;
  87. // Returns true if this key's lifetime is short-lived, or if
  88. // IsFullyPopulated() returns true. It may not make sense to persist state to
  89. // disk related to it (e.g., disk cache).
  90. bool IsTransient() const;
  91. // Getters for the top frame and frame sites. These accessors are primarily
  92. // intended for IPC calls, and to be able to create an IsolationInfo from a
  93. // NetworkIsolationKey.
  94. const absl::optional<SchemefulSite>& GetTopFrameSite() const {
  95. return top_frame_site_;
  96. }
  97. const absl::optional<SchemefulSite>& GetFrameSite() const;
  98. // Getter for the nonce.
  99. const absl::optional<base::UnguessableToken>& GetNonce() const {
  100. return nonce_;
  101. }
  102. // Returns true if all parts of the key are empty.
  103. bool IsEmpty() const;
  104. // Returns true if the NetworkIsolationKey has a triple keyed scheme. This
  105. // means both `frame_site_` and `top_frame_site_` are populated.
  106. static bool IsFrameSiteEnabled();
  107. // Returns a representation of |this| as a base::Value. Returns false on
  108. // failure. Succeeds if either IsEmpty() or !IsTransient().
  109. [[nodiscard]] bool ToValue(base::Value* out_value) const;
  110. // Inverse of ToValue(). Writes the result to |network_isolation_key|. Returns
  111. // false on failure. Fails on values that could not have been produced by
  112. // ToValue(), like transient origins. If the value of
  113. // net::features::kAppendFrameOriginToNetworkIsolationKey has changed between
  114. // saving and loading the data, fails.
  115. [[nodiscard]] static bool FromValue(
  116. const base::Value& value,
  117. NetworkIsolationKey* out_network_isolation_key);
  118. private:
  119. // Whether this key has opaque origins or a nonce.
  120. bool IsOpaque() const;
  121. // SchemefulSite::Serialize() is not const, as it may initialize the nonce.
  122. // Need this to call it on a const |site|.
  123. static absl::optional<std::string> SerializeSiteWithNonce(
  124. const SchemefulSite& site);
  125. // The origin/etld+1 of the top frame of the page making the request.
  126. absl::optional<SchemefulSite> top_frame_site_;
  127. // The origin/etld+1 of the frame that initiates the request.
  128. absl::optional<SchemefulSite> frame_site_;
  129. // Having a nonce is a way to force a transient opaque `NetworkIsolationKey`
  130. // for non-opaque origins.
  131. absl::optional<base::UnguessableToken> nonce_;
  132. };
  133. } // namespace net
  134. #endif // NET_BASE_NETWORK_ISOLATION_KEY_H_