Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
/* Defines the abstract interface for a principal. */
7
8
#include "nsIContentSecurityPolicy.idl"
9
#include "nsISerializable.idl"
10
#include "nsIAboutModule.idl"
11
#include "nsIReferrerInfo.idl"
12
13
%{C++
14
struct JSPrincipals;
15
#include "nsCOMPtr.h"
16
#include "nsTArray.h"
17
#include "nsString.h"
18
#include "mozilla/DebugOnly.h"
19
namespace mozilla {
20
class OriginAttributes;
21
}
22
23
/**
24
* Some methods have a fast path for the case when we're comparing a principal
25
* to itself. The situation may happen for example with about:blank documents.
26
*/
27
28
#define DECL_FAST_INLINE_HELPER(method_) \
29
inline bool method_(nsIPrincipal* aOther) \
30
{ \
31
mozilla::DebugOnly<bool> val = false; \
32
MOZ_ASSERT_IF(this == aOther, \
33
NS_SUCCEEDED(method_(aOther, &val)) && val); \
34
\
35
bool retVal = false; \
36
return \
37
this == aOther || \
38
(NS_SUCCEEDED(method_(aOther, &retVal)) && retVal); \
39
}
40
41
%}
42
43
interface nsIURI;
44
45
[ptr] native JSContext(JSContext);
46
[ptr] native JSPrincipals(JSPrincipals);
47
[ref] native PrincipalArray(const nsTArray<nsCOMPtr<nsIPrincipal>>);
48
[ref] native const_OriginAttributes(const mozilla::OriginAttributes);
49
native ReferrerPolicy(mozilla::dom::ReferrerPolicy);
50
51
[scriptable, builtinclass, uuid(f75f502d-79fd-48be-a079-e5a7b8f80c8b)]
52
interface nsIPrincipal : nsISerializable
53
{
54
/**
55
* Returns whether the other principal is equivalent to this principal.
56
* Principals are considered equal if they are the same principal, or
57
* they have the same origin.
58
*/
59
boolean equals(in nsIPrincipal other);
60
61
/**
62
* Like equals, but takes document.domain changes into account.
63
*/
64
boolean equalsConsideringDomain(in nsIPrincipal other);
65
66
%{C++
67
DECL_FAST_INLINE_HELPER(Equals)
68
DECL_FAST_INLINE_HELPER(EqualsConsideringDomain)
69
%}
70
71
/*
72
* Returns whether the Principals URI is equal to the other URI
73
*/
74
boolean equalsURI(in nsIURI aOtherURI);
75
76
/**
77
* Returns a hash value for the principal.
78
*/
79
[notxpcom, nostdcall] readonly attribute unsigned long hashValue;
80
81
/**
82
* The principal URI to which this principal pertains. This is
83
* generally the document URI.
84
*/
85
[infallible] readonly attribute nsIURI URI;
86
87
/**
88
* The domain URI to which this principal pertains.
89
* This is null unless script successfully sets document.domain to our URI
90
* or a superdomain of our URI.
91
* Setting this has no effect on the URI.
93
*/
94
[noscript] attribute nsIURI domain;
95
96
/**
97
* Returns whether the other principal is equal to or weaker than this
98
* principal. Principals are equal if they are the same object or they
99
* have the same origin.
100
*
101
* Thus a principal always subsumes itself.
102
*
103
* The system principal subsumes itself and all other principals.
104
*
105
* A null principal (corresponding to an unknown, hence assumed minimally
106
* privileged, security context) is not equal to any other principal
107
* (including other null principals), and therefore does not subsume
108
* anything but itself.
109
*/
110
boolean subsumes(in nsIPrincipal other);
111
112
/**
113
* Same as the previous method, subsumes(), but takes document.domain into
114
* account.
115
*/
116
boolean subsumesConsideringDomain(in nsIPrincipal other);
117
118
/**
119
* Same as the subsumesConsideringDomain(), but ignores the first party
120
* domain in its originAttributes.
121
*/
122
boolean subsumesConsideringDomainIgnoringFPD(in nsIPrincipal other);
123
124
%{C++
125
DECL_FAST_INLINE_HELPER(Subsumes)
126
DECL_FAST_INLINE_HELPER(SubsumesConsideringDomain)
127
DECL_FAST_INLINE_HELPER(SubsumesConsideringDomainIgnoringFPD)
128
#undef DECL_FAST_INLINE_HELPER
129
%}
130
131
/**
132
* Checks whether this principal is allowed to load the network resource
133
* located at the given URI under the same-origin policy. This means that
134
* content principals are only allowed to load resources from the same
135
* domain, the system principal is allowed to load anything, and null
136
* principals can only load URIs where they are the principal. This is
137
* changed by the optional flag allowIfInheritsPrincipal (which defaults to
138
* false) which allows URIs that inherit their loader's principal.
139
*
140
* If the load is allowed this function does nothing. If the load is not
141
* allowed the function throws NS_ERROR_DOM_BAD_URI.
142
*
143
* NOTE: Other policies might override this, such as the Access-Control
144
* specification.
145
* NOTE: The 'domain' attribute has no effect on the behaviour of this
146
* function.
147
*
148
*
149
* @param uri The URI about to be loaded.
150
* @param allowIfInheritsPrincipal If true, the load is allowed if the
151
* loadee inherits the principal of the
152
* loader.
153
* @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
154
*/
155
void checkMayLoad(in nsIURI uri,
156
in boolean allowIfInheritsPrincipal);
157
158
/**
159
* Like checkMayLoad, but if returning an error will also report that error
160
* to the console, using the provided window id. The window id may be 0 to
161
* report to just the browser console, not web consoles.
162
*/
163
void checkMayLoadWithReporting(in nsIURI uri,
164
in boolean allowIfInheritsPrincipal,
165
in unsigned long long innerWindowID);
166
167
/**
168
* Checks if the provided URI is concidered third-party to the
169
* URI of the principal.
170
* Returns true if the URI is third-party.
171
*
172
* @param uri - The URI to check
173
*/
174
boolean isThirdPartyURI(in nsIURI uri);
175
176
/**
177
* Checks if the provided principal is concidered third-party to the
178
* URI of the Principal.
179
* Returns true if the principal is third-party.
180
*
181
* @param principal - The principal to check
182
*/
183
boolean isThirdPartyPrincipal(in nsIPrincipal principal);
184
185
/**
186
* A dictionary of the non-default origin attributes associated with this
187
* nsIPrincipal.
188
*
189
* Attributes are tokens that are taken into account when determining whether
190
* two principals are same-origin - if any attributes differ, the principals
191
* are cross-origin, even if the scheme, host, and port are the same.
192
* Attributes should also be considered for all security and bucketing decisions,
193
* even those which make non-standard comparisons (like cookies, which ignore
194
* scheme, or quotas, which ignore subdomains).
195
*
196
* If you're looking for an easy-to-use canonical stringification of the origin
197
* attributes, see |originSuffix| below.
198
*/
199
[implicit_jscontext]
200
readonly attribute jsval originAttributes;
201
202
[noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)]
203
const_OriginAttributes OriginAttributesRef();
204
205
/**
206
* A canonical representation of the origin for this principal. This
207
* consists of a base string (which, for content principals, is of the
208
* format scheme://host:port), concatenated with |originAttributes| (see
209
* below).
210
*
211
* We maintain the invariant that principalA.equals(principalB) if and only
212
* if principalA.origin == principalB.origin.
213
*/
214
readonly attribute ACString origin;
215
216
/**
217
* Returns an ASCII compatible representation
218
* of the principals Origin
219
*/
220
[noscript] readonly attribute ACString asciiOrigin;
221
222
/**
223
* Returns the "host:port" portion of the
224
* Principals URI, if any.
225
*/
226
[noscript] readonly attribute ACString hostPort;
227
228
/**
229
* Returns the "host:port" portion of the
230
* Principals URI, if any.
231
*/
232
[noscript] readonly attribute ACString asciiHost;
233
234
235
/**
236
* Returns the "host" portion of the
237
* Principals URI, if any.
238
*/
239
[noscript] readonly attribute ACString host;
240
241
/**
242
* Returns the prepath of the principals uri
243
* follows the format scheme:
245
*/
246
[noscript] readonly attribute ACString prepath;
247
248
/**
249
* Returns the ASCII Spec from the Principals URI.
250
* Might return the empty string, e.g. for the case of
251
* a SystemPrincipal or an EpxandedPrincipal.
252
*
253
* WARNING: DO NOT USE FOR SECURITY CHECKS.
254
* just for logging purposes!
255
*/
256
[noscript] readonly attribute ACString asciiSpec;
257
258
/* Returns the Pre Path of the Principals URI with
259
* user:pass stripped for privacy and spoof prevention
260
*/
261
readonly attribute ACString exposablePrePath;
262
263
/**
264
* Checks if the Principal's URI Scheme matches with the parameter
265
*
266
* @param scheme The scheme to be checked
267
*/
268
boolean schemeIs(in string scheme);
269
270
// Nicer, C++ Callable Version of SchemeIs
271
%{C++
272
inline bool SchemeIs(const char* aScheme) {
273
bool ret;
274
SchemeIs(aScheme, &ret);
275
return ret;
276
}
277
%}
278
279
/*
280
* Checks if the Principal's URI is contained in the given Pref
281
* @param pref The pref to be checked
282
*/
283
bool isURIInPrefList(in string pref);
284
285
/*
286
* Uses NS_Security Compare to determine if the
287
* other URI is same-origin as the uri of the Principal
288
*/
289
bool isSameOrigin(in nsIURI otherURI, in bool aIsPrivateWin);
290
291
/*
292
* Checks if the Principal is allowed to load the Provided file:// URI
293
* using NS_RelaxStrictFileOriginPolicy
294
*/
295
bool allowsRelaxStrictFileOriginPolicy(in nsIURI aURI);
296
297
298
/*
299
* Generates a Cache-Key for the Cors-Preflight Cache
300
*/
301
ACString getPrefLightCacheKey(in nsIURI aURI ,in bool aWithCredentials);
302
303
304
/*
305
* Returns a Key for the LocalStorage Manager, used to
306
* check the Principals Origin Storage usage.
307
*/
308
readonly attribute ACString localStorageQuotaKey;
309
310
/**
311
* Implementation of
313
*
314
* The value returned by this method feeds into the the Secure Context
315
* algorithm that determins the value of Window.isSecureContext and
316
* WorkerGlobalScope.isSecureContext.
317
*
318
* This method returns false instead of throwing upon errors.
319
*/
320
readonly attribute bool isOriginPotentiallyTrustworthy;
321
322
/**
323
* Returns the Flags of the Principals
324
* associated AboutModule, in case there is one.
325
*/
326
uint32_t getAboutModuleFlags();
327
328
/*
329
* Returns the Key to access the Principals
330
* Origin Local/Session Storage
331
*/
332
readonly attribute ACString storageOriginKey;
333
334
/**
335
* Creates and Returns a new ReferrerInfo with the
336
* Principals URI
337
*/
338
nsIReferrerInfo createReferrerInfo(in ReferrerPolicy aReferrerPolicy);
339
340
/**
341
* The base part of |origin| without the concatenation with |originSuffix|.
342
* This doesn't have the important invariants described above with |origin|,
343
* and as such should only be used for legacy situations.
344
*/
345
readonly attribute ACString originNoSuffix;
346
347
/**
348
* A string of the form !key1=value1&key2=value2, where each pair represents
349
* an attribute with a non-default value. If all attributes have default
350
* values, this is the empty string.
351
*
352
* The value of .originSuffix is automatically serialized into .origin, so any
353
* consumers using that are automatically origin-attribute-aware. Consumers with
354
* special requirements must inspect and compare .originSuffix manually.
355
*/
356
readonly attribute AUTF8String originSuffix;
357
358
/**
359
* A canonical representation of the site-origin for this principal.
360
* This string has the same format as |origin| (see above). Two principals
361
* with differing |siteOrigin| values will never compare equal, even when
362
* considering domain mutations.
363
*
364
* For most principals, |siteOrigin| matches |origin| precisely. Only
365
* principals which allow mutating |domain|, such as ContentPrincipal,
366
* override the default implementation in BasePrincipal.
367
*
368
* TODO(nika): Use this in DocGroup.
369
*/
370
readonly attribute ACString siteOrigin;
371
372
/**
373
* The base domain of the principal URI to which this principal pertains
374
* (generally the document URI), handling null principals and
375
* non-hierarchical schemes correctly.
376
*/
377
readonly attribute ACString baseDomain;
378
379
/**
380
* Gets the ID of the add-on this principal belongs to.
381
*/
382
readonly attribute AString addonId;
383
384
readonly attribute nsISupports addonPolicy;
385
386
/**
387
* Gets the id of the user context this principal is inside. If this
388
* principal is inside the default userContext, this returns
389
* nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
390
*/
391
[infallible] readonly attribute unsigned long userContextId;
392
393
/**
394
* Gets the id of the private browsing state of the context containing
395
* this principal. If the principal has a private browsing value of 0, it
396
* is not in private browsing.
397
*/
398
[infallible] readonly attribute unsigned long privateBrowsingId;
399
400
/**
401
* Returns true iff the principal is inside an isolated mozbrowser element.
402
* <xul:browser> is not considered to be a mozbrowser element.
403
* <iframe mozbrowser noisolation> does not count as isolated since
404
* isolation is disabled. Isolation can only be disabled if the
405
* containing document is chrome.
406
*/
407
[infallible] readonly attribute boolean isInIsolatedMozBrowserElement;
408
409
/**
410
* Returns true iff this is a null principal (corresponding to an
411
* unknown, hence assumed minimally privileged, security context).
412
*/
413
[infallible] readonly attribute boolean isNullPrincipal;
414
415
/**
416
* Returns true iff this principal corresponds to a principal origin.
417
*/
418
[infallible] readonly attribute boolean isContentPrincipal;
419
420
/**
421
* Returns true iff this is an expanded principal.
422
*/
423
[infallible] readonly attribute boolean isExpandedPrincipal;
424
425
/**
426
* Returns true iff this is the system principal. C++ callers should use
427
* IsSystemPrincipal() instead of this scriptable accessor.
428
*/
429
readonly attribute boolean isSystemPrincipal;
430
431
/**
432
* Faster and nicer version callable from C++. Callers must include
433
* BasePrincipal.h, where it's implemented.
434
*/
435
%{C++
436
inline bool IsSystemPrincipal() const;
437
%}
438
439
/**
440
* Returns true iff the principal is either an addon principal or
441
* an expanded principal, which contains at least one addon principal.
442
*/
443
[infallible] readonly attribute boolean isAddonOrExpandedAddonPrincipal;
444
445
%{C++
446
// MOZ_DBG support
447
friend std::ostream& operator<<(std::ostream& aOut, const nsIPrincipal& aPrincipal) {
448
nsIPrincipal* principal = const_cast<nsIPrincipal*>(&aPrincipal);
449
nsAutoCString origin;
450
mozilla::DebugOnly<nsresult> rv = principal->GetOrigin(origin);
451
MOZ_ASSERT(NS_SUCCEEDED(rv));
452
return aOut << "nsIPrincipal { " << origin << " }";
453
}
454
%}
455
/*
456
* Returns true if the URI is an Onion URI
457
*/
458
[infallible] readonly attribute boolean isOnion;
459
460
/*
461
* Returns true if the Domain Policy allows js execution
462
* for the Principals URI
463
*/
464
readonly attribute boolean isScriptAllowedByPolicy;
465
466
467
/*
468
* Returns true if the Principal can acess l10n
469
* features for the Provided DocumentURI
470
*/
471
boolean isL10nAllowed(in nsIURI aDocumentURI);
472
473
/**
474
* Returns if the principal is for an IP address.
475
*/
476
[infallible] readonly attribute boolean isIpAddress;
477
};
478
479
/**
480
* If SystemPrincipal is too risky to use, but we want a principal to access
481
* more than one origin, ExpandedPrincipals letting us define an array of
482
* principals it subsumes. So script with an ExpandedPrincipals will gain
483
* same origin access when at least one of its principals it contains gained
484
* sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
485
* principal, and by another ExpandedPrincipal that has all its principals.
486
* It is added for jetpack content-scripts to let them interact with the
487
* content and a well defined set of other domains, without the risk of
488
* leaking out a system principal to the content. See: Bug 734891
489
*/
490
[uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)]
491
interface nsIExpandedPrincipal : nsISupports
492
{
493
/**
494
* An array of principals that the expanded principal subsumes.
495
*
496
* When an expanded principal is used as a triggering principal for a
497
* request that inherits a security context, one of its constitutent
498
* principals is inherited rather than the expanded principal itself. The
499
* last principal in the allowlist is the default principal to inherit.
500
*
501
* Note: this list is not reference counted, it is shared, so
502
* should not be changed and should only be used ephemerally.
503
*/
504
[noscript, notxpcom, nostdcall]
505
PrincipalArray AllowList();
506
507
508
/**
509
* Bug 1548468: Move CSP off ExpandedPrincipal.
510
*
511
* A Content Security Policy associated with this principal. Use this function
512
* to query the associated CSP with this principal.
513
*/
514
readonly attribute nsIContentSecurityPolicy csp;
515
516
%{ C++
517
inline already_AddRefed<nsIContentSecurityPolicy> GetCsp()
518
{
519
nsCOMPtr<nsIContentSecurityPolicy> result;
520
mozilla::DebugOnly<nsresult> rv = GetCsp(getter_AddRefs(result));
521
MOZ_ASSERT(NS_SUCCEEDED(rv));
522
return result.forget();
523
}
524
%}
525
526
};