1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/mozIThirdPartyUtil.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,238 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +#include "nsISupports.idl"
1.9 +
1.10 +interface nsIURI;
1.11 +interface nsIDOMWindow;
1.12 +interface nsIChannel;
1.13 +interface nsIDocument;
1.14 +
1.15 +/**
1.16 + * Utility functions for determining whether a given URI, channel, or window
1.17 + * hierarchy is third party with respect to a known URI.
1.18 + */
1.19 +[scriptable, uuid(d994fd1d-d2fe-4372-9ae7-88b08b7d9d90)]
1.20 +interface mozIThirdPartyUtil : nsISupports
1.21 +{
1.22 + /**
1.23 + * isThirdPartyURI
1.24 + *
1.25 + * Determine whether two URIs are third party with respect to each other.
1.26 + * This is determined by computing the base domain for both URIs. If they can
1.27 + * be determined, and the base domains match, the request is defined as first
1.28 + * party. If it cannot be determined because one or both URIs do not have a
1.29 + * base domain (for instance, in the case of IP addresses, host aliases such
1.30 + * as 'localhost', or a file:// URI), an exact string comparison on host is
1.31 + * performed.
1.32 + *
1.33 + * For example, the URI "http://mail.google.com/" is not third party with
1.34 + * respect to "http://images.google.com/", but "http://mail.yahoo.com/" and
1.35 + * "http://192.168.1.1/" are.
1.36 + *
1.37 + * @return true if aFirstURI is third party with respect to aSecondURI.
1.38 + *
1.39 + * @throws if either URI is null, has a malformed host, or has an empty host
1.40 + * and is not a file:// URI.
1.41 + */
1.42 + boolean isThirdPartyURI(in nsIURI aFirstURI, in nsIURI aSecondURI);
1.43 +
1.44 + /**
1.45 + * isThirdPartyWindow
1.46 + *
1.47 + * Determine whether the given window hierarchy is third party. This is done
1.48 + * as follows:
1.49 + *
1.50 + * 1) Obtain the URI of the principal associated with 'aWindow'. Call this the
1.51 + * 'bottom URI'.
1.52 + * 2) If 'aURI' is provided, determine if it is third party with respect to
1.53 + * the bottom URI. If so, return.
1.54 + * 3) Find the same-type parent window, if there is one, and its URI.
1.55 + * Determine whether it is third party with respect to the bottom URI. If
1.56 + * so, return.
1.57 + *
1.58 + * Therefore, each level in the window hierarchy is tested. (This means that
1.59 + * nested iframes with different base domains, even though the bottommost and
1.60 + * topmost URIs might be equal, will be considered third party.)
1.61 + *
1.62 + * @param aWindow
1.63 + * The bottommost window in the hierarchy.
1.64 + * @param aURI
1.65 + * A URI to test against. If null, the URI of the principal
1.66 + * associated with 'aWindow' will be used.
1.67 + *
1.68 + * For example, if 'aURI' is "http://mail.google.com/", 'aWindow' has a URI
1.69 + * of "http://google.com/", and its parent is the topmost content window with
1.70 + * a URI of "http://mozilla.com", the result will be true.
1.71 + *
1.72 + * @return true if 'aURI' is third party with respect to any of the URIs
1.73 + * associated with aWindow and its same-type parents.
1.74 + *
1.75 + * @throws if aWindow is null; the same-type parent of any window in the
1.76 + * hierarchy cannot be determined; or the URI associated with any
1.77 + * window in the hierarchy is null, has a malformed host, or has an
1.78 + * empty host and is not a file:// URI.
1.79 + *
1.80 + * @see isThirdPartyURI
1.81 + */
1.82 + boolean isThirdPartyWindow(in nsIDOMWindow aWindow, [optional] in nsIURI aURI);
1.83 +
1.84 + /**
1.85 + * isThirdPartyChannel
1.86 + *
1.87 + * Determine whether the given channel and its content window hierarchy is
1.88 + * third party. This is done as follows:
1.89 + *
1.90 + * 1) If 'aChannel' is an nsIHttpChannel and has the
1.91 + * 'forceAllowThirdPartyCookie' property set, then:
1.92 + * a) If 'aURI' is null, return false.
1.93 + * b) Otherwise, find the URI of the channel, determine whether it is
1.94 + * foreign with respect to 'aURI', and return.
1.95 + * 2) Find the URI of the channel and determine whether it is third party with
1.96 + * respect to the URI of the channel. If so, return.
1.97 + * 3) Obtain the bottommost nsIDOMWindow, and its same-type parent if it
1.98 + * exists, from the channel's notification callbacks. Then:
1.99 + * a) If the parent is the same as the bottommost window, and the channel
1.100 + * has the LOAD_DOCUMENT_URI flag set, return false. This represents the
1.101 + * case where a toplevel load is occurring and the window's URI has not
1.102 + * yet been updated. (We have already checked that 'aURI' is not foreign
1.103 + * with respect to the channel URI.)
1.104 + * b) Otherwise, return the result of isThirdPartyWindow with arguments
1.105 + * of the channel's bottommost window and the channel URI, respectively.
1.106 + *
1.107 + * Therefore, both the channel's URI and each level in the window hierarchy
1.108 + * associated with the channel is tested.
1.109 + *
1.110 + * @param aChannel
1.111 + * The channel associated with the load.
1.112 + * @param aURI
1.113 + * A URI to test against. If null, the URI of the channel will be used.
1.114 + *
1.115 + * For example, if 'aURI' is "http://mail.google.com/", 'aChannel' has a URI
1.116 + * of "http://google.com/", and its parent is the topmost content window with
1.117 + * a URI of "http://mozilla.com", the result will be true.
1.118 + *
1.119 + * @return true if aURI is third party with respect to the channel URI or any
1.120 + * of the URIs associated with the same-type window hierarchy of the
1.121 + * channel.
1.122 + *
1.123 + * @throws if 'aChannel' is null; the channel has no notification callbacks or
1.124 + * an associated window; or isThirdPartyWindow throws.
1.125 + *
1.126 + * @see isThirdPartyWindow
1.127 + */
1.128 + boolean isThirdPartyChannel(in nsIChannel aChannel, [optional] in nsIURI aURI);
1.129 +
1.130 + /**
1.131 + * getBaseDomain
1.132 + *
1.133 + * Get the base domain for aHostURI; e.g. for "www.bbc.co.uk", this would be
1.134 + * "bbc.co.uk". Only properly-formed URI's are tolerated, though a trailing
1.135 + * dot may be present. If aHostURI is an IP address, an alias such as
1.136 + * 'localhost', an eTLD such as 'co.uk', or the empty string, aBaseDomain will
1.137 + * be the exact host. The result of this function should only be used in exact
1.138 + * string comparisons, since substring comparisons will not be valid for the
1.139 + * special cases elided above.
1.140 + *
1.141 + * @param aHostURI
1.142 + * The URI to analyze.
1.143 + *
1.144 + * @return the base domain.
1.145 + */
1.146 + AUTF8String getBaseDomain(in nsIURI aHostURI);
1.147 +
1.148 +
1.149 + /**
1.150 + * getFirstPartyURI
1.151 + *
1.152 + * Obtain the top-level url bar URI for either a channel or a document.
1.153 + * Either parameter may be null (but not both).
1.154 + *
1.155 + * @param aChannel
1.156 + * An arbitrary channel for some content element of a first party
1.157 + * load. Can be null.
1.158 + *
1.159 + * @param aDoc
1.160 + * An arbitrary third party document. Can be null.
1.161 + *
1.162 + * @return the first party url bar URI for the load.
1.163 + *
1.164 + * @throws if the URI cannot be obtained or the URI lacks a hostname and the
1.165 + * URI's scheme is not white listed.
1.166 + */
1.167 + [noscript] nsIURI getFirstPartyURI(in nsIChannel aChannel,
1.168 + in nsIDocument aDoc);
1.169 +
1.170 + /**
1.171 + * getFirstPartyIsolationURI
1.172 + *
1.173 + * If first-party isolation is active, then
1.174 + * obtains the top-level url bar URI for either a channel or a document.
1.175 + * Otherwise returns null.
1.176 + * Either parameter may be null (but not both).
1.177 + *
1.178 + * @param aChannel
1.179 + * An arbitrary channel for some content element of a first party
1.180 + * load. Can be null.
1.181 + *
1.182 + * @param aDoc
1.183 + * An arbitrary third party document. Can be null.
1.184 + *
1.185 + * @return the first party url bar URI for the load.
1.186 + *
1.187 + * @throws if the URI cannot be obtained or the URI lacks a hostname and the
1.188 + * URI's scheme is not white listed.
1.189 + */
1.190 + [noscript] nsIURI getFirstPartyIsolationURI(in nsIChannel aChannel,
1.191 + in nsIDocument aDoc);
1.192 +
1.193 + /**
1.194 + * getFirstPartyURIFromChannel
1.195 + *
1.196 + * Obtain the top-level url bar URI for a channel.
1.197 + *
1.198 + * @param aChannel
1.199 + * An arbitrary channel for some content element of a first party
1.200 + * load.
1.201 + *
1.202 + * @param aLogErrors
1.203 + * If true, log errors to the Error Console.
1.204 + *
1.205 + * @return the first party url bar URI for the load.
1.206 + *
1.207 + * @throws if the URI cannot be obtained or the URI lacks a hostname and the
1.208 + * URI's scheme is not white listed.
1.209 + */
1.210 + nsIURI getFirstPartyURIFromChannel(in nsIChannel aChannel,
1.211 + in bool aLogErrors);
1.212 +
1.213 + /**
1.214 + * getFirstPartyHostForIsolation
1.215 + *
1.216 + * Obtain the host or pseudo-host for aFirstPartyURI. Some examples:
1.217 + * aFirstPartyURI Return Value
1.218 + * -------------- ------------
1.219 + * https://news.google.com/nwshp?hl=en "news.google.com"
1.220 + * about:home "--NoFirstPartyHost-about-home--"
1.221 + * chrome://browser/content/browser.xul "--NoFirstPartyHost-chrome-browser.xul--"
1.222 + *
1.223 + * @param aFirstPartyURI
1.224 + * The first party URI.
1.225 + *
1.226 + * @return host or pseudo host.
1.227 + *
1.228 + * @throws if the URI lacks a host and the scheme is not a whitelisted one
1.229 + * for which we generate a pseudo host.
1.230 + */
1.231 + AUTF8String getFirstPartyHostForIsolation(in nsIURI aFirstPartyURI);
1.232 +};
1.233 +
1.234 +%{ C++
1.235 +/**
1.236 + * The mozIThirdPartyUtil implementation is an XPCOM service registered
1.237 + * under the ContractID:
1.238 + */
1.239 +#define THIRDPARTYUTIL_CONTRACTID "@mozilla.org/thirdpartyutil;1"
1.240 +%}
1.241 +
