netwerk/base/public/mozIThirdPartyUtil.idl@b8a032363ba2
netwerk/base/public/mozIThirdPartyUtil.idl
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
1 /* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5 #include "nsISupports.idl"
7 interface nsIURI;
8 interface nsIDOMWindow;
9 interface nsIChannel;
10 interface nsIDocument;
12 /**
13 * Utility functions for determining whether a given URI, channel, or window
14 * hierarchy is third party with respect to a known URI.
15 */
16 [scriptable, uuid(d994fd1d-d2fe-4372-9ae7-88b08b7d9d90)]
17 interface mozIThirdPartyUtil : nsISupports
18 {
19 /**
20 * isThirdPartyURI
21 *
22 * Determine whether two URIs are third party with respect to each other.
23 * This is determined by computing the base domain for both URIs. If they can
24 * be determined, and the base domains match, the request is defined as first
25 * party. If it cannot be determined because one or both URIs do not have a
26 * base domain (for instance, in the case of IP addresses, host aliases such
27 * as 'localhost', or a file:// URI), an exact string comparison on host is
28 * performed.
29 *
30 * For example, the URI "http://mail.google.com/" is not third party with
31 * respect to "http://images.google.com/", but "http://mail.yahoo.com/" and
32 * "http://192.168.1.1/" are.
33 *
34 * @return true if aFirstURI is third party with respect to aSecondURI.
35 *
36 * @throws if either URI is null, has a malformed host, or has an empty host
37 * and is not a file:// URI.
38 */
39 boolean isThirdPartyURI(in nsIURI aFirstURI, in nsIURI aSecondURI);
41 /**
42 * isThirdPartyWindow
43 *
44 * Determine whether the given window hierarchy is third party. This is done
45 * as follows:
46 *
47 * 1) Obtain the URI of the principal associated with 'aWindow'. Call this the
48 * 'bottom URI'.
49 * 2) If 'aURI' is provided, determine if it is third party with respect to
50 * the bottom URI. If so, return.
51 * 3) Find the same-type parent window, if there is one, and its URI.
52 * Determine whether it is third party with respect to the bottom URI. If
53 * so, return.
54 *
55 * Therefore, each level in the window hierarchy is tested. (This means that
56 * nested iframes with different base domains, even though the bottommost and
57 * topmost URIs might be equal, will be considered third party.)
58 *
59 * @param aWindow
60 * The bottommost window in the hierarchy.
61 * @param aURI
62 * A URI to test against. If null, the URI of the principal
63 * associated with 'aWindow' will be used.
64 *
65 * For example, if 'aURI' is "http://mail.google.com/", 'aWindow' has a URI
66 * of "http://google.com/", and its parent is the topmost content window with
67 * a URI of "http://mozilla.com", the result will be true.
68 *
69 * @return true if 'aURI' is third party with respect to any of the URIs
70 * associated with aWindow and its same-type parents.
71 *
72 * @throws if aWindow is null; the same-type parent of any window in the
73 * hierarchy cannot be determined; or the URI associated with any
74 * window in the hierarchy is null, has a malformed host, or has an
75 * empty host and is not a file:// URI.
76 *
77 * @see isThirdPartyURI
78 */
79 boolean isThirdPartyWindow(in nsIDOMWindow aWindow, [optional] in nsIURI aURI);
81 /**
82 * isThirdPartyChannel
83 *
84 * Determine whether the given channel and its content window hierarchy is
85 * third party. This is done as follows:
86 *
87 * 1) If 'aChannel' is an nsIHttpChannel and has the
88 * 'forceAllowThirdPartyCookie' property set, then:
89 * a) If 'aURI' is null, return false.
90 * b) Otherwise, find the URI of the channel, determine whether it is
91 * foreign with respect to 'aURI', and return.
92 * 2) Find the URI of the channel and determine whether it is third party with
93 * respect to the URI of the channel. If so, return.
94 * 3) Obtain the bottommost nsIDOMWindow, and its same-type parent if it
95 * exists, from the channel's notification callbacks. Then:
96 * a) If the parent is the same as the bottommost window, and the channel
97 * has the LOAD_DOCUMENT_URI flag set, return false. This represents the
98 * case where a toplevel load is occurring and the window's URI has not
99 * yet been updated. (We have already checked that 'aURI' is not foreign
100 * with respect to the channel URI.)
101 * b) Otherwise, return the result of isThirdPartyWindow with arguments
102 * of the channel's bottommost window and the channel URI, respectively.
103 *
104 * Therefore, both the channel's URI and each level in the window hierarchy
105 * associated with the channel is tested.
106 *
107 * @param aChannel
108 * The channel associated with the load.
109 * @param aURI
110 * A URI to test against. If null, the URI of the channel will be used.
111 *
112 * For example, if 'aURI' is "http://mail.google.com/", 'aChannel' has a URI
113 * of "http://google.com/", and its parent is the topmost content window with
114 * a URI of "http://mozilla.com", the result will be true.
115 *
116 * @return true if aURI is third party with respect to the channel URI or any
117 * of the URIs associated with the same-type window hierarchy of the
118 * channel.
119 *
120 * @throws if 'aChannel' is null; the channel has no notification callbacks or
121 * an associated window; or isThirdPartyWindow throws.
122 *
123 * @see isThirdPartyWindow
124 */
125 boolean isThirdPartyChannel(in nsIChannel aChannel, [optional] in nsIURI aURI);
127 /**
128 * getBaseDomain
129 *
130 * Get the base domain for aHostURI; e.g. for "www.bbc.co.uk", this would be
131 * "bbc.co.uk". Only properly-formed URI's are tolerated, though a trailing
132 * dot may be present. If aHostURI is an IP address, an alias such as
133 * 'localhost', an eTLD such as 'co.uk', or the empty string, aBaseDomain will
134 * be the exact host. The result of this function should only be used in exact
135 * string comparisons, since substring comparisons will not be valid for the
136 * special cases elided above.
137 *
138 * @param aHostURI
139 * The URI to analyze.
140 *
141 * @return the base domain.
142 */
143 AUTF8String getBaseDomain(in nsIURI aHostURI);
146 /**
147 * getFirstPartyURI
148 *
149 * Obtain the top-level url bar URI for either a channel or a document.
150 * Either parameter may be null (but not both).
151 *
152 * @param aChannel
153 * An arbitrary channel for some content element of a first party
154 * load. Can be null.
155 *
156 * @param aDoc
157 * An arbitrary third party document. Can be null.
158 *
159 * @return the first party url bar URI for the load.
160 *
161 * @throws if the URI cannot be obtained or the URI lacks a hostname and the
162 * URI's scheme is not white listed.
163 */
164 [noscript] nsIURI getFirstPartyURI(in nsIChannel aChannel,
165 in nsIDocument aDoc);
167 /**
168 * getFirstPartyIsolationURI
169 *
170 * If first-party isolation is active, then
171 * obtains the top-level url bar URI for either a channel or a document.
172 * Otherwise returns null.
173 * Either parameter may be null (but not both).
174 *
175 * @param aChannel
176 * An arbitrary channel for some content element of a first party
177 * load. Can be null.
178 *
179 * @param aDoc
180 * An arbitrary third party document. Can be null.
181 *
182 * @return the first party url bar URI for the load.
183 *
184 * @throws if the URI cannot be obtained or the URI lacks a hostname and the
185 * URI's scheme is not white listed.
186 */
187 [noscript] nsIURI getFirstPartyIsolationURI(in nsIChannel aChannel,
188 in nsIDocument aDoc);
190 /**
191 * getFirstPartyURIFromChannel
192 *
193 * Obtain the top-level url bar URI for a channel.
194 *
195 * @param aChannel
196 * An arbitrary channel for some content element of a first party
197 * load.
198 *
199 * @param aLogErrors
200 * If true, log errors to the Error Console.
201 *
202 * @return the first party url bar URI for the load.
203 *
204 * @throws if the URI cannot be obtained or the URI lacks a hostname and the
205 * URI's scheme is not white listed.
206 */
207 nsIURI getFirstPartyURIFromChannel(in nsIChannel aChannel,
208 in bool aLogErrors);
210 /**
211 * getFirstPartyHostForIsolation
212 *
213 * Obtain the host or pseudo-host for aFirstPartyURI. Some examples:
214 * aFirstPartyURI Return Value
215 * -------------- ------------
216 * https://news.google.com/nwshp?hl=en "news.google.com"
217 * about:home "--NoFirstPartyHost-about-home--"
218 * chrome://browser/content/browser.xul "--NoFirstPartyHost-chrome-browser.xul--"
219 *
220 * @param aFirstPartyURI
221 * The first party URI.
222 *
223 * @return host or pseudo host.
224 *
225 * @throws if the URI lacks a host and the scheme is not a whitelisted one
226 * for which we generate a pseudo host.
227 */
228 AUTF8String getFirstPartyHostForIsolation(in nsIURI aFirstPartyURI);
229 };
231 %{ C++
232 /**
233 * The mozIThirdPartyUtil implementation is an XPCOM service registered
234 * under the ContractID:
235 */
236 #define THIRDPARTYUTIL_CONTRACTID "@mozilla.org/thirdpartyutil;1"
237 %}
