Source code

Revision control

Other Tools

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/. */
4
5
#include "nsISupports.idl"
6
7
interface nsIURI;
8
interface mozIDOMWindowProxy;
9
interface nsIChannel;
10
interface nsIPrincipal;
11
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(fd82700e-ffb4-4932-b7d6-08f0b5697dda)]
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);
40
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 mozIDOMWindowProxy aWindow, [optional] in nsIURI aURI);
80
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);
126
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);
144
145
/**
146
* NOTE: Long term, this method won't be needed once bug 922464 is fixed which
147
* will make it possible to parse all URI's off the main thread.
148
*
149
* getBaseDomainFromSchemeHost
150
*
151
* Get the base domain for aScheme and aHost. Otherwise identical to
152
* getBaseDomain().
153
*
154
* @param aScheme
155
* The scheme to analyze.
156
*
157
* @param aAsciiHost
158
* The host to analyze.
159
*
160
* @return the base domain.
161
*/
162
AUTF8String getBaseDomainFromSchemeHost(in AUTF8String aScheme,
163
in AUTF8String aAsciiHost);
164
165
/**
166
* getURIFromWindow
167
*
168
* Returns the URI associated with the script object principal for the
169
* window.
170
*/
171
nsIURI getURIFromWindow(in mozIDOMWindowProxy aWindow);
172
173
/**
174
* getPrincipalFromWindow
175
*
176
* Returns the script object principal for the window.
177
*/
178
nsIPrincipal getPrincipalFromWindow(in mozIDOMWindowProxy aWindow);
179
180
/**
181
* getContentBlockingAllowListPrincipalFromWindow
182
*
183
* Returns the content blocking allow list principal for the window.
184
*/
185
[noscript]
186
nsIPrincipal getContentBlockingAllowListPrincipalFromWindow(in mozIDOMWindowProxy aWindow,
187
[optional] in nsIURI aURIBeingLoaded);
188
189
/**
190
* getTopWindowForChannel
191
*
192
* Returns the top-level window associated with the given channel.
193
*/
194
[noscript]
195
mozIDOMWindowProxy getTopWindowForChannel(in nsIChannel aChannel, [optional] in nsIURI aURIBeingLoaded);
196
};
197
198
%{ C++
199
/**
200
* The mozIThirdPartyUtil implementation is an XPCOM service registered
201
* under the ContractID:
202
*/
203
#define THIRDPARTYUTIL_CONTRACTID "@mozilla.org/thirdpartyutil;1"
204
%}
205