• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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