url/origin.h

   1 // Copyright 2015 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
   5 #ifndef URL_ORIGIN_H_
   6 #define URL_ORIGIN_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11
  12 #include "base/debug/alias.h"
  13 #include "base/strings/string16.h"
  14 #include "base/strings/string_piece.h"
  15 #include "url/scheme_host_port.h"
  16 #include "url/third_party/mozilla/url_parse.h"
  17 #include "url/url_canon.h"
  18 #include "url/url_constants.h"
  19 #include "url/url_export.h"
  20
  21 class GURL;
  22
  23 namespace url {
  24
  25 // An Origin is a tuple of (scheme, host, port), as described in RFC 6454.
  26 //
  27 // TL;DR: If you need to make a security-relevant decision, use 'url::Origin'.
  28 // If you only need to extract the bits of a URL which are relevant for a
  29 // network connection, use 'url::SchemeHostPort'.
  30 //
  31 // STL;SDR: If you aren't making actual network connections, use 'url::Origin'.
  32 //
  33 // 'Origin', like 'SchemeHostPort', is composed of a tuple of (scheme, host,
  34 // port), but contains a number of additional concepts which make it appropriate
  35 // for use as a security boundary and access control mechanism between contexts.
  36 //
  37 // This class ought to be used when code needs to determine if two resources
  38 // are "same-origin", and when a canonical serialization of an origin is
  39 // required. Note that some origins are "unique", meaning that they are not
  40 // same-origin with any other origin (including themselves).
  41 //
  42 // There are a few subtleties to note:
  43 //
  44 // * Invalid and non-standard GURLs are parsed as unique origins. This includes
  45 //   non-hierarchical URLs like 'data:text/html,...' and 'javascript:alert(1)'.
  46 //
  47 // * GURLs with schemes of 'filesystem' or 'blob' parse the origin out of the
  48 //   internals of the URL. That is, 'filesystem:https://example.com/temporary/f'
  49 //   is parsed as ('https', 'example.com', 443).
  50 //
  51 // * Unique origins all serialize to the string "null"; this means that the
  52 //   serializations of two unique origins are identical to each other, though
  53 //   the origins themselves are not "the same". This means that origins'
  54 //   serializations must not be relied upon for security checks.
  55 //
  56 // * GURLs with a 'file' scheme are tricky. They are parsed as ('file', '', 0),
  57 //   but their behavior may differ from embedder to embedder.
  58 //
  59 // * The host component of an IPv6 address includes brackets, just like the URL
  60 //   representation.
  61 //
  62 // Usage:
  63 //
  64 // * Origins are generally constructed from an already-canonicalized GURL:
  65 //
  66 //     GURL url("https://example.com/");
  67 //     url::Origin origin(url);
  68 //     origin.scheme(); // "https"
  69 //     origin.host(); // "example.com"
  70 //     origin.port(); // 443
  71 //     origin.unique(); // false
  72 //
  73 // * To answer the question "Are |this| and |that| "same-origin" with each
  74 //   other?", use |Origin::IsSameOriginWith|:
  75 //
  76 //     if (this.IsSameOriginWith(that)) {
  77 //       // Amazingness goes here.
  78 //     }
  79 class URL_EXPORT Origin {
  80  public:
  81   // Creates a unique Origin.
  82   Origin();
  83
  84   // Creates an Origin from |url|, as described at
  85   // https://url.spec.whatwg.org/#origin, with the following additions:
  86   //
  87   // 1. If |url| is invalid or non-standard, a unique Origin is constructed.
  88   // 2. 'filesystem' URLs behave as 'blob' URLs (that is, the origin is parsed
  89   //    out of everything in the URL which follows the scheme).
  90   // 3. 'file' URLs all parse as ("file", "", 0).
  91   static Origin Create(const GURL& url);
  92
  93   // Copyable and movable.
  94   Origin(const Origin&);
  95   Origin& operator=(const Origin&);
  96   Origin(Origin&&);
  97   Origin& operator=(Origin&&);
  98
  99   // Creates an Origin from a |scheme|, |host|, and |port|. All the parameters
 100   // must be valid and canonicalized. Do not use this method to create unique
 101   // origins. Use Origin() for that.
 102   //
 103   // This constructor should be used in order to pass 'Origin' objects back and
 104   // forth over IPC (as transitioning through GURL would risk potentially
 105   // dangerous recanonicalization); other potential callers should prefer the
 106   // 'GURL'-based constructor.
 107   static Origin UnsafelyCreateOriginWithoutNormalization(
 108       base::StringPiece scheme,
 109       base::StringPiece host,
 110       uint16_t port);
 111
 112   // Creates an origin without sanity checking that the host is canonicalized.
 113   // This should only be used when converting between already normalized types,
 114   // and should NOT be used for IPC. Method takes std::strings for use with move
 115   // operators to avoid copies.
 116   static Origin CreateFromNormalizedTuple(std::string scheme,
 117                                           std::string host,
 118                                           uint16_t port);
 119
 120   ~Origin();
 121
 122   // For unique origins, these return ("", "", 0).
 123   const std::string& scheme() const { return tuple_.scheme(); }
 124   const std::string& host() const { return tuple_.host(); }
 125   uint16_t port() const { return tuple_.port(); }
 126
 127   bool unique() const { return unique_; }
 128
 129   // An ASCII serialization of the Origin as per Section 6.2 of RFC 6454, with
 130   // the addition that all Origins with a 'file' scheme serialize to "file://".
 131   std::string Serialize() const;
 132
 133   // Two Origins are "same-origin" if their schemes, hosts, and ports are exact
 134   // matches; and neither is unique.
 135   bool IsSameOriginWith(const Origin& other) const;
 136   bool operator==(const Origin& other) const {
 137     return IsSameOriginWith(other);
 138   }
 139
 140   // Efficiently returns what GURL(Serialize()) would without re-parsing the
 141   // URL. This can be used for the (rare) times a GURL representation is needed
 142   // for an Origin.
 143   // Note: The returned URL will not necessarily be serialized to the same value
 144   // as the Origin would. The GURL will have an added "/" path for Origins with
 145   // valid SchemeHostPorts and file Origins.
 146   //
 147   // Try not to use this method under normal circumstances, as it loses type
 148   // information. Downstream consumers can mistake the returned GURL with a full
 149   // URL (e.g. with a path component).
 150   GURL GetURL() const;
 151
 152   // Same as GURL::DomainIs. If |this| origin is unique, then returns false.
 153   bool DomainIs(base::StringPiece canonical_domain) const;
 154
 155   // Allows Origin to be used as a key in STL (for example, a std::set or
 156   // std::map).
 157   bool operator<(const Origin& other) const;
 158
 159  private:
 160   // |tuple| must be valid, implying that the created Origin is never unique.
 161   explicit Origin(SchemeHostPort tuple);
 162
 163   SchemeHostPort tuple_;
 164   bool unique_;
 165 };
 166
 167 URL_EXPORT std::ostream& operator<<(std::ostream& out, const Origin& origin);
 168
 169 URL_EXPORT bool IsSameOriginWith(const GURL& a, const GURL& b);
 170
 171 // DEBUG_ALIAS_FOR_ORIGIN(var_name, origin) copies |origin| into a new
 172 // stack-allocated variable named |<var_name>|.  This helps ensure that the
 173 // value of |origin| gets preserved in crash dumps.
 174 #define DEBUG_ALIAS_FOR_ORIGIN(var_name, origin) \
 175   DEBUG_ALIAS_FOR_CSTR(var_name, origin.Serialize().c_str(), 128)
 176
 177 }  // namespace url
 178
 179 #endif  // URL_ORIGIN_H_