Implement new referrer policies

net/url_request/url_request.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef NET_URL_REQUEST_URL_REQUEST_H_
 #define NET_URL_REQUEST_URL_REQUEST_H_
 
 #include <stdint.h>
 
 #include <memory>
@@ skipping 69 matching lines @@
                                            const std::string& scheme);
 
   // A ReferrerPolicy for the request can be set with
   // set_referrer_policy() and controls the contents of the Referer
   // header when URLRequest follows server redirects. Note that setting
   // a ReferrerPolicy on the request has no effect on the Referer header
   // of the initial leg of the request; the caller is responsible for
   // setting the initial Referer, and the ReferrerPolicy only controls
   // what happens to the Referer while following redirects.
   enum ReferrerPolicy {
-    // Clear the referrer header if the protocol changes from HTTPS to
-    // HTTP. This is the default behavior of URLRequest.
+    // Clear the referrer header if the header value is HTTPS but the request
+    // destination is HTTP. This is the default behavior of URLRequest.
     CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE,
-    // A slight variant on
-    // CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE: If the
-    // request downgrades from HTTPS to HTTP, the referrer will be
-    // cleared. If the request transitions cross-origin (but does not
-    // downgrade), the referrer's granularity will be reduced (currently
-    // stripped down to an origin rather than a full URL). Same-origin
-    // requests will send the full referrer.
+    // A slight variant on CLEAR_REFERRER_ON_TRANSITION_FROM_SECURE_TO_INSECURE:
+    // If the request destination is HTTP, an HTTPS referrer will be cleared. If
+    // the request's destination is cross-origin with the referrer (but does not
+    // downgrade), the referrer's granularity will be stripped down to an origin
+    // rather than a full URL. Same-origin requests will send the full referrer.
     REDUCE_REFERRER_GRANULARITY_ON_TRANSITION_CROSS_ORIGIN,
-    // Strip the referrer down to an origin upon cross-origin navigation.
+    // Strip the referrer down to an origin when the origin of the referrer is
+    // different from the destination's origin.
     ORIGIN_ONLY_ON_TRANSITION_CROSS_ORIGIN,
     // Never change the referrer.
     NEVER_CLEAR_REFERRER,
     // Strip the referrer down to the origin regardless of the redirect
     // location.
     ORIGIN,
-    // Always clear the referrer regardless of the redirect location.
+    // Clear the referrer when the request's referrer is cross-origin with
+    // the request's destination.
+    CLEAR_REFERRER_ON_TRANSITION_CROSS_ORIGIN,
+    // Strip the referrer down to the origin, but clear it entirely if the
+    // referrer value is HTTPS and the destination is HTTP.
+    ORIGIN_CLEAR_ON_TRANSITION_FROM_SECURE_TO_INSECURE,
+    // Always clear the referrer regardless of the request destination.
     NO_REFERRER,
     MAX_REFERRER_POLICY
   };
 
   // First-party URL redirect policy: During server redirects, the first-party
   // URL for cookies normally doesn't change. However, if the request is a
   // top-level first-party request, the first-party URL should be updated to the
   // URL on every redirect.
   enum FirstPartyURLPolicy {
     NEVER_CHANGE_FIRST_PARTY_URL,
@@ skipping 188 matching lines @@
   const base::Optional<url::Origin>& initiator() const { return initiator_; }
   // This method may only be called before Start().
   void set_initiator(const base::Optional<url::Origin>& initiator);
 
   // The request method, as an uppercase string.  "GET" is the default value.
   // The request method may only be changed before Start() is called and
   // should only be assigned an uppercase value.
   const std::string& method() const { return method_; }
   void set_method(const std::string& method);
 
-  // The referrer URL for the request.  This header may actually be suppressed
-  // from the underlying network request for security reasons (e.g., a HTTPS
-  // URL will not be sent as the referrer for a HTTP request).  The referrer
-  // may only be changed before Start() is called.
+  // The referrer URL for the request
   const std::string& referrer() const { return referrer_; }
-  // Referrer is sanitized to remove URL fragment, user name and password.
+  // Sets the referrer URL for the request. Can only be changed before Start()
+  // is called. |referrer| is sanitized to remove URL fragment, user name and
+  // password. If a referrer policy is set via set_referrer_policy(), then
+  // |referrer| should obey the policy; if it doesn't, it will be cleared when
+  // the request is started. The referrer URL may be suppressed or changed
+  // during the course of the request, for example because of a referrer policy
+  // set with set_referrer_policy().
   void SetReferrer(const std::string& referrer);
 
   // The referrer policy to apply when updating the referrer during redirects.
-  // The referrer policy may only be changed before Start() is called.
+  // The referrer policy may only be changed before Start() is called. Any
+  // referrer set via SetReferrer() is expected to obey the policy set via
+  // set_referrer_policy(); otherwise the referrer will be cleared when the
+  // request is started.
   ReferrerPolicy referrer_policy() const { return referrer_policy_; }
   void set_referrer_policy(ReferrerPolicy referrer_policy);
 
   // If this request should include a referred Token Binding, this returns the
   // hostname of the referrer that indicated this request should include a
   // referred Token Binding. Otherwise, this returns the empty string.
   const std::string& token_binding_referrer() const {
     return token_binding_referrer_;
   }
 
@@ skipping 524 matching lines @@
   const NetworkTrafficAnnotationTag traffic_annotation_;
 
   THREAD_CHECKER(thread_checker_);
 
   DISALLOW_COPY_AND_ASSIGN(URLRequest);
 };
 
 }  // namespace net
 
 #endif  // NET_URL_REQUEST_URL_REQUEST_H_