1 // Copyright 2022 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_BASE_NETWORK_ANONYMIZATION_KEY_H_ 6 #define NET_BASE_NETWORK_ANONYMIZATION_KEY_H_ 7 8 #include <cstddef> 9 #include <string> 10 #include <tuple> 11 12 #include "base/unguessable_token.h" 13 #include "net/base/net_export.h" 14 #include "net/base/network_isolation_key.h" 15 #include "net/base/schemeful_site.h" 16 #include "third_party/abseil-cpp/absl/types/optional.h" 17 18 namespace base { 19 class Value; 20 } 21 22 namespace net { 23 24 // NetworkAnonymizationKey will be used to partition shared network state based 25 // on the context on which they were made. This class is an expiremental key 26 // that contains properties that will be changed via feature flags. 27 28 // NetworkAnonymizationKey contains the following properties: 29 30 // `top_frame_site` represents the SchemefulSite of the pages top level frame. 31 // In order to separate first and third party context from each other this field 32 // will always be populated. 33 34 // `is_cross_site` indicates whether the key is cross-site or same-site. A 35 // same-site key indicates that he schemeful site of the top frame and the frame 36 // are the same. Intermediary frames between the two may be cross-site to them. 37 // The effect of this property is to partition first-party and third-party 38 // resources within a given `top_frame_site`. 39 40 // The following show how the `is_cross_site` boolean is populated for the 41 // innermost frame in the chain. 42 // a->a => is_cross_site = false 43 // a->b => is_cross_site = true 44 // a->b->a => is_cross_site = false 45 // a->(sandboxed a [has nonce]) => is_cross_site = true 46 47 // The `nonce` value creates a key for anonymous iframes by giving them a 48 // temporary `nonce` value which changes per top level navigation. For now, any 49 // NetworkAnonymizationKey with a nonce will be considered transient. This is 50 // being considered to possibly change in the future in an effort to allow 51 // anonymous iframes with the same partition key access to shared resources. 52 // The nonce value will be empty except for anonymous iframes. 53 54 // TODO @brgoldstein, add link to public documentation of key scheme naming 55 // conventions. 56 57 class NET_EXPORT NetworkAnonymizationKey { 58 public: 59 // Construct an empty key. 60 NetworkAnonymizationKey(); 61 62 NetworkAnonymizationKey( 63 const NetworkAnonymizationKey& network_anonymization_key); 64 NetworkAnonymizationKey(NetworkAnonymizationKey&& network_anonymization_key); 65 66 ~NetworkAnonymizationKey(); 67 68 NetworkAnonymizationKey& operator=( 69 const NetworkAnonymizationKey& network_anonymization_key); 70 NetworkAnonymizationKey& operator=( 71 NetworkAnonymizationKey&& network_anonymization_key); 72 73 // Compare keys for equality, true if all enabled fields are equal. 74 bool operator==(const NetworkAnonymizationKey& other) const { 75 return std::tie(top_frame_site_, is_cross_site_, nonce_) == 76 std::tie(other.top_frame_site_, other.is_cross_site_, other.nonce_); 77 } 78 79 // Compare keys for inequality, true if any enabled field varies. 80 bool operator!=(const NetworkAnonymizationKey& other) const { 81 return !(*this == other); 82 } 83 84 // Provide an ordering for keys based on all enabled fields. 85 bool operator<(const NetworkAnonymizationKey& other) const { 86 return std::tie(top_frame_site_, is_cross_site_, nonce_) < 87 std::tie(other.top_frame_site_, other.is_cross_site_, other.nonce_); 88 } 89 90 // Create a `NetworkAnonymizationKey` from a `top_frame_site`, assuming it is 91 // same-site (see comment on the class, above) and has no nonce. CreateSameSite(const SchemefulSite & top_frame_site)92 static NetworkAnonymizationKey CreateSameSite( 93 const SchemefulSite& top_frame_site) { 94 return NetworkAnonymizationKey(top_frame_site, false, absl::nullopt); 95 } 96 97 // Create a `NetworkAnonymizationKey` from a `top_frame_site`, assuming it is 98 // cross-site (see comment on the class, above) and has no nonce. CreateCrossSite(const SchemefulSite & top_frame_site)99 static NetworkAnonymizationKey CreateCrossSite( 100 const SchemefulSite& top_frame_site) { 101 return NetworkAnonymizationKey(top_frame_site, true, absl::nullopt); 102 } 103 104 // Create a `NetworkAnonymizationKey` from a `top_frame_site` and 105 // `frame_site`. This calculates is_cross_site on the basis of those two 106 // sites. 107 static NetworkAnonymizationKey CreateFromFrameSite( 108 const SchemefulSite& top_frame_site, 109 const SchemefulSite& frame_site, 110 absl::optional<base::UnguessableToken> nonce = absl::nullopt); 111 112 // Creates a `NetworkAnonymizationKey` from a `NetworkIsolationKey`. This is 113 // possible because a `NetworkIsolationKey` must always be more granular 114 // than a `NetworkAnonymizationKey`. 115 static NetworkAnonymizationKey CreateFromNetworkIsolationKey( 116 const net::NetworkIsolationKey& network_isolation_key); 117 118 // Creates a `NetworkAnonymizationKey` from its constituent parts. This 119 // is intended to be used to build a NAK from Mojo, and for tests. 120 static NetworkAnonymizationKey CreateFromParts( 121 const SchemefulSite& top_frame_site, 122 bool is_cross_site, 123 absl::optional<base::UnguessableToken> nonce = absl::nullopt) { 124 return NetworkAnonymizationKey(top_frame_site, is_cross_site, nonce); 125 } 126 127 // TODO(crbug/1372769) 128 // Intended for temporary use in locations that should be using main frame and 129 // frame origin, but are currently only using frame origin, because the 130 // creating object may be shared across main frame objects. Having a special 131 // constructor for these methods makes it easier to keep track of locating 132 // callsites that need to have their NetworkAnonymizationKey filled in. ToDoUseTopFrameOriginAsWell(const url::Origin & incorrectly_used_frame_origin)133 static NetworkAnonymizationKey ToDoUseTopFrameOriginAsWell( 134 const url::Origin& incorrectly_used_frame_origin) { 135 net::SchemefulSite incorrectly_used_frame_site = 136 net::SchemefulSite(incorrectly_used_frame_origin); 137 return NetworkAnonymizationKey(incorrectly_used_frame_site, false); 138 } 139 140 // Creates a transient non-empty NetworkAnonymizationKey by creating an opaque 141 // origin. This prevents the NetworkAnonymizationKey from sharing data with 142 // other NetworkAnonymizationKey. 143 static NetworkAnonymizationKey CreateTransient(); 144 145 // Returns the string representation of the key. 146 std::string ToDebugString() const; 147 148 // Returns true if all parts of the key are empty. 149 bool IsEmpty() const; 150 151 // Returns true if `top_frame_site_` is non-empty. 152 bool IsFullyPopulated() const; 153 154 // Returns true if this key's lifetime is short-lived. It may not make sense 155 // to persist state to disk related to it (e.g., disk cache). 156 // A NetworkAnonymizationKey will be considered transient if 157 // `top_frame_site_` is empty or opaque or if the key has a `nonce_`. 158 bool IsTransient() const; 159 160 // Getters for the top frame, frame site, nonce and is cross site flag. GetTopFrameSite()161 const absl::optional<SchemefulSite>& GetTopFrameSite() const { 162 return top_frame_site_; 163 } 164 IsCrossSite()165 bool IsCrossSite() const { return is_cross_site_; } 166 IsSameSite()167 bool IsSameSite() const { return !IsCrossSite(); } 168 GetNonce()169 const absl::optional<base::UnguessableToken>& GetNonce() const { 170 return nonce_; 171 } 172 173 // Returns a representation of |this| as a base::Value. Returns false on 174 // failure. Succeeds if either IsEmpty() or !IsTransient(). 175 [[nodiscard]] bool ToValue(base::Value* out_value) const; 176 177 // Inverse of ToValue(). Writes the result to |network_anonymization_key|. 178 // Returns false on failure. Fails on values that could not have been produced 179 // by ToValue(), like transient origins. 180 [[nodiscard]] static bool FromValue( 181 const base::Value& value, 182 NetworkAnonymizationKey* out_network_anonymization_key); 183 184 // Determine whether network state partitioning is enabled. This is true if 185 // any of the features 186 // 187 // * `SplitHostCacheByNetworkIsolationKey` 188 // * `PartitionConnectionsByNetworkIsolationKey` 189 // * `PartitionHttpServerPropertiesByNetworkIsolationKey` 190 // * `PartitionSSLSessionsByNetworkIsolationKey` 191 // * `PartitionNelAndReportingByNetworkIsolationKey` 192 // 193 // is enabled, or if `PartitionByDefault()` has been called. 194 static bool IsPartitioningEnabled(); 195 196 // Default partitioning to enabled, regardless of feature settings. This must 197 // be called before any calls to `IsPartitioningEnabled()`. 198 static void PartitionByDefault(); 199 200 // Clear partitioning-related globals. 201 static void ClearGlobalsForTesting(); 202 203 private: 204 NetworkAnonymizationKey( 205 const SchemefulSite& top_frame_site, 206 bool is_cross_site, 207 absl::optional<base::UnguessableToken> nonce = absl::nullopt); 208 209 std::string GetSiteDebugString( 210 const absl::optional<SchemefulSite>& site) const; 211 212 static absl::optional<std::string> SerializeSiteWithNonce( 213 const SchemefulSite& site); 214 215 // The origin/etld+1 of the top frame of the page making the request. This 216 // will always be populated unless all other fields are also nullopt. 217 absl::optional<SchemefulSite> top_frame_site_; 218 219 // True if the frame site is cross site when compared to the top frame site. 220 // This is always false for a non-fully-populated NAK. 221 bool is_cross_site_; 222 223 // for non-opaque origins. 224 absl::optional<base::UnguessableToken> nonce_; 225 }; 226 227 } // namespace net 228 229 #endif // NET_BASE_NETWORK_ANONYMIZATION_KEY_H_ 230