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 <string>
   9
  10 #include "base/strings/string16.h"
  11 #include "base/strings/string_piece.h"
  12 #include "url/scheme_host_port.h"
  13 #include "url/third_party/mozilla/url_parse.h"
  14 #include "url/url_canon.h"
  15 #include "url/url_constants.h"
  16 #include "url/url_export.h"
  17
  18 class GURL;
  19
  20 namespace url {
  21
  22 // An Origin is a tuple of (scheme, host, port), as described in RFC 6454.
  23 //
  24 // TL;DR: If you need to make a security-relevant decision, use 'url::Origin'.
  25 // If you only need to extract the bits of a URL which are relevant for a
  26 // network connection, use 'url::SchemeHostPort'.
  27 //
  28 // STL;SDR: If you aren't making actual network connections, use 'url::Origin'.
  29 //
  30 // 'Origin', like 'SchemeHostPort', is composed of a tuple of (scheme, host,
  31 // port), but contains a number of additional concepts which make it appropriate
  32 // for use as a security boundary and access control mechanism between contexts.
  33 //
  34 // This class ought to be used when code needs to determine if two resources
  35 // are "same-origin", and when a canonical serialization of an origin is
  36 // required. Note that some origins are "unique", meaning that they are not
  37 // same-origin with any other origin (including themselves).
  38 //
  39 // There are a few subtleties to note:
  40 //
  41 // * Invalid and non-standard GURLs are parsed as unique origins. This includes
  42 //   non-hierarchical URLs like 'data:text/html,...' and 'javascript:alert(1)'.
  43 //
  44 // * GURLs with schemes of 'filesystem' or 'blob' parse the origin out of the
  45 //   internals of the URL. That is, 'filesystem:https://example.com/temporary/f'
  46 //   is parsed as ('https', 'example.com', 443).
  47 //
  48 // * Unique origins all serialize to the string "null"; this means that the
  49 //   serializations of two unique origins are identical to each other, though
  50 //   the origins themselves are not "the same". This means that origins'
  51 //   serializations must not be relied upon for security checks.
  52 //
  53 // * GURLs with a 'file' scheme are tricky. They are parsed as ('file', '', 0),
  54 //   but their behavior may differ from embedder to embedder.
  55 //
  56 // * The host component of an IPv6 address includes brackets, just like the URL
  57 //   representation.
  58 //
  59 // Usage:
  60 //
  61 // * Origins are generally constructed from an already-canonicalized GURL:
  62 //
  63 //     GURL url("https://example.com/");
  64 //     url::Origin origin(url);
  65 //     origin.scheme(); // "https"
  66 //     origin.host(); // "example.com"
  67 //     origin.port(); // 443
  68 //     origin.IsUnique(); // false
  69 //
  70 // * To answer the question "Are |this| and |that| "same-origin" with each
  71 //   other?", use |Origin::IsSameOriginWith|:
  72 //
  73 //     if (this.IsSameOriginWith(that)) {
  74 //       // Amazingness goes here.
  75 //     }
  76 class URL_EXPORT Origin {
  77  public:
  78   // Creates a unique Origin.
  79   Origin();
  80
  81   // Creates an Origin from |url|, as described at
  82   // https://url.spec.whatwg.org/#origin, with the following additions:
  83   //
  84   // 1. If |url| is invalid or non-standard, a unique Origin is constructed.
  85   // 2. 'filesystem' URLs behave as 'blob' URLs (that is, the origin is parsed
  86   //    out of everything in the URL which follows the scheme).
  87   // 3. 'file' URLs all parse as ("file", "", 0).
  88   explicit Origin(const GURL& url);
  89
  90   // Creates an Origin from a |scheme|, |host|, and |port|. All the parameters
  91   // must be valid and canonicalized. In particular, note that this cannot be
  92   // used to create unique origins; 'url::Origin()' is the right way to do that.
  93   //
  94   // This constructor should be used in order to pass 'Origin' objects back and
  95   // forth over IPC (as transitioning through GURL would risk potentially
  96   // dangerous recanonicalization); other potential callers should prefer the
  97   // 'GURL'-based constructor.
  98   static Origin UnsafelyCreateOriginWithoutNormalization(
  99       base::StringPiece scheme,
 100       base::StringPiece host,
 101       uint16 port);
 102
 103   ~Origin();
 104
 105   // For unique origins, these return ("", "", 0).
 106   const std::string& scheme() const { return tuple_.scheme(); }
 107   const std::string& host() const { return tuple_.host(); }
 108   uint16 port() const { return tuple_.port(); }
 109
 110   bool unique() const { return unique_; }
 111
 112   // An ASCII serialization of the Origin as per Section 6.2 of RFC 6454, with
 113   // the addition that all Origins with a 'file' scheme serialize to "file://".
 114   std::string Serialize() const;
 115
 116   // Two Origins are "same-origin" if their schemes, hosts, and ports are exact
 117   // matches; and neither is unique.
 118   bool IsSameOriginWith(const Origin& other) const;
 119
 120   // Allows SchemeHostPort to used as a key in STL (for example, a std::set or
 121   // std::map).
 122   bool operator<(const Origin& other) const;
 123
 124  private:
 125   Origin(base::StringPiece scheme, base::StringPiece host, uint16 port);
 126
 127   SchemeHostPort tuple_;
 128   bool unique_;
 129 };
 130
 131 URL_EXPORT std::ostream& operator<<(std::ostream& out,
 132                                     const Origin& origin);
 133
 134 }  // namespace url
 135
 136 #endif  // URL_SCHEME_HOST_PORT_H_