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/. */
6 /* Defines the abstract interface for a principal. */
8 #include
"nsIContentSecurityPolicy.idl"
9 #include
"nsISerializable.idl"
10 #include
"nsIAboutModule.idl"
11 #include
"nsIReferrerInfo.idl"
13 #include
"mozIDOMWindow.idl"
20 #include
"mozilla/DebugOnly.h"
22 class OriginAttributes
;
26 * Some methods have a fast path for the case when we're comparing a principal
27 * to itself. The situation may happen for example with about:blank documents.
30 #define DECL_FAST_INLINE_HELPER
(method_
) \
31 inline bool method_
(nsIPrincipal
* aOther
) \
33 mozilla
::DebugOnly
<bool
> val
= false
; \
34 MOZ_ASSERT_IF
(this
== aOther
, \
35 NS_SUCCEEDED
(method_
(aOther
, &val
)) && val
); \
37 bool
retVal = false
; \
40 (NS_SUCCEEDED
(method_
(aOther
, &retVal)) && retVal); \
47 [ptr] native JSContext
(JSContext
);
48 [ptr] native JSPrincipals
(JSPrincipals
);
49 [ref] native PrincipalArray
(const nsTArray
<nsCOMPtr
<nsIPrincipal
>>);
50 [ref] native const_OriginAttributes
(const mozilla
::OriginAttributes
);
51 native ReferrerPolicy
(mozilla
::dom
::ReferrerPolicy
);
53 [scriptable
, builtinclass
, uuid(f75f502d
-79fd
-48be
-a079
-e5a7b8f80c8b
)]
54 interface nsIPrincipal
: nsISerializable
57 * Returns whether the other principal is equivalent to this principal.
58 * Principals are considered equal if they are the same principal, or
59 * they have the same origin.
61 boolean equals
(in nsIPrincipal other
);
64 * Returns whether the other principal is equivalent to this principal
65 * for permission purposes
66 * Matches {originAttributes ,equalsURIForPermission}
69 boolean equalsForPermission
(in nsIPrincipal other
, in bool aExactHost
);
72 * Like equals, but takes document.domain changes into account.
74 boolean equalsConsideringDomain
(in nsIPrincipal other
);
77 DECL_FAST_INLINE_HELPER
(Equals
)
78 DECL_FAST_INLINE_HELPER
(EqualsConsideringDomain
)
82 * Returns whether the Principals URI is equal to the other URI
84 boolean equalsURI
(in nsIURI aOtherURI
);
87 * Returns a hash value for the principal.
89 [notxpcom
, nostdcall
] readonly attribute
unsigned long hashValue
;
92 * The principal URI to which this principal pertains. This is
93 * generally the document URI.
95 [infallible
] readonly attribute nsIURI URI
;
98 * The domain URI to which this principal pertains.
99 * This is null unless script successfully sets document.domain to our URI
100 * or a superdomain of our URI.
101 * Setting this has no effect on the URI.
102 * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin
104 [noscript
] attribute nsIURI domain
;
107 * Returns whether the other principal is equal to or weaker than this
108 * principal. Principals are equal if they are the same object or they
109 * have the same origin.
111 * Thus a principal always subsumes itself.
113 * The system principal subsumes itself and all other principals.
115 * A null principal (corresponding to an unknown, hence assumed minimally
116 * privileged, security context) is not equal to any other principal
117 * (including other null principals), and therefore does not subsume
118 * anything but itself.
120 boolean subsumes
(in nsIPrincipal other
);
123 * Same as the previous method, subsumes(), but takes document.domain into
126 boolean subsumesConsideringDomain
(in nsIPrincipal other
);
129 * Same as the subsumesConsideringDomain(), but ignores the first party
130 * domain in its originAttributes.
132 boolean subsumesConsideringDomainIgnoringFPD
(in nsIPrincipal other
);
135 DECL_FAST_INLINE_HELPER
(Subsumes
)
136 DECL_FAST_INLINE_HELPER
(SubsumesConsideringDomain
)
137 DECL_FAST_INLINE_HELPER
(SubsumesConsideringDomainIgnoringFPD
)
138 #undef DECL_FAST_INLINE_HELPER
142 * Checks whether this principal is allowed to load the network resource
143 * located at the given URI under the same-origin policy. This means that
144 * content principals are only allowed to load resources from the same
145 * domain, the system principal is allowed to load anything, and null
146 * principals can only load URIs where they are the principal. This is
147 * changed by the optional flag allowIfInheritsPrincipal (which defaults to
148 * false) which allows URIs that inherit their loader's principal.
150 * If the load is allowed this function does nothing. If the load is not
151 * allowed the function throws NS_ERROR_DOM_BAD_URI.
153 * NOTE: Other policies might override this, such as the Access-Control
155 * NOTE: The 'domain' attribute has no effect on the behaviour of this
159 * @param uri The URI about to be loaded.
160 * @param allowIfInheritsPrincipal If true, the load is allowed if the
161 * loadee inherits the principal of the
163 * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
165 void checkMayLoad
(in nsIURI uri
,
166 in boolean allowIfInheritsPrincipal
);
169 * Like checkMayLoad, but if returning an error will also report that error
170 * to the console, using the provided window id. The window id may be 0 to
171 * report to just the browser console, not web consoles.
173 void checkMayLoadWithReporting
(in nsIURI uri
,
174 in boolean allowIfInheritsPrincipal
,
175 in unsigned long long innerWindowID
);
178 * Checks if the provided URI is considered third-party to the
179 * URI of the principal.
180 * Returns true if the URI is third-party.
182 * @param uri - The URI to check
184 boolean isThirdPartyURI
(in nsIURI uri
);
187 * Checks if the provided principal is considered third-party to the
188 * URI of the Principal.
189 * Returns true if the principal is third-party.
191 * @param principal - The principal to check
193 boolean isThirdPartyPrincipal
(in nsIPrincipal principal
);
196 * Checks if the provided channel is considered third-party to the
197 * URI of the principal.
198 * Returns true if the channel is third-party.
199 * Returns false if the Principal is a System Principal
201 * @param channel - The Channel to check
203 boolean isThirdPartyChannel
(in nsIChannel channel
);
206 * A dictionary of the non-default origin attributes associated with this
209 * Attributes are tokens that are taken into account when determining whether
210 * two principals are same-origin - if any attributes differ, the principals
211 * are cross-origin, even if the scheme, host, and port are the same.
212 * Attributes should also be considered for all security and bucketing decisions,
213 * even those which make non-standard comparisons (like cookies, which ignore
214 * scheme, or quotas, which ignore subdomains).
216 * If you're looking for an easy-to-use canonical stringification of the origin
217 * attributes, see |originSuffix| below.
220 readonly attribute jsval originAttributes
;
222 [noscript
, notxpcom
, nostdcall
, binaryname
(OriginAttributesRef
)]
223 const_OriginAttributes OriginAttributesRef
();
226 * A canonical representation of the origin for this principal. This
227 * consists of a base string (which, for content principals, is of the
228 * format scheme://host:port), concatenated with |originAttributes| (see
231 * We maintain the invariant that principalA.equals(principalB) if and only
232 * if principalA.origin == principalB.origin.
234 readonly attribute ACString origin
;
237 * Returns an ASCII compatible representation
238 * of the principals Origin
240 [noscript
] readonly attribute ACString asciiOrigin
;
243 * Returns the "host:port" portion of the
244 * Principals URI, if any.
246 readonly attribute ACString hostPort
;
249 * Returns the "host:port" portion of the
250 * Principals URI, if any.
252 readonly attribute ACString asciiHost
;
255 * Returns the "host" portion of the
256 * Principals URI, if any.
258 readonly attribute ACString host
;
261 * Returns the prepath of the principals uri
262 * follows the format scheme:
263 * "scheme://username:password@hostname:portnumber/"
265 readonly attribute ACString prepath
;
268 * Returns the filePath of the principals uri. See nsIURI.
270 readonly attribute ACString filePath
;
273 * Returns the ASCII Spec from the Principals URI.
274 * Might return the empty string, e.g. for the case of
275 * a SystemPrincipal or an EpxandedPrincipal.
277 * WARNING: DO NOT USE FOR SECURITY CHECKS.
278 * just for logging purposes!
280 readonly attribute ACString asciiSpec
;
283 * Returns the Spec from the Principals URI.
284 * Might return the empty string, e.g. for the case of
285 * a SystemPrincipal or an EpxandedPrincipal.
287 * WARNING: Do not land new Code using, as this will be removed soon
289 readonly attribute ACString spec
;
291 /* Returns the Pre Path of the Principals URI with
292 * user:pass stripped for privacy and spoof prevention
294 readonly attribute ACString exposablePrePath
;
296 /* Returns the Spec of the Principals URI with
297 * user/pass/ref/query stripped for privacy and spoof prevention
299 readonly attribute ACString exposableSpec
;
302 * Return the scheme of the principals URI
304 readonly attribute ACString scheme
;
307 * Checks if the Principal's URI Scheme matches with the parameter
309 * @param scheme The scheme to be checked
312 boolean schemeIs
(in string scheme
);
315 * Checks if the Principal's URI is contained in the given Pref
316 * @param pref The pref to be checked
319 boolean isURIInPrefList
(in string pref
);
322 * Uses NS_Security Compare to determine if the
323 * other URI is same-origin as the uri of the Principal
325 bool isSameOrigin
(in nsIURI otherURI
, in bool aIsPrivateWin
);
328 * Checks if the Principal is allowed to load the Provided file:// URI
329 * using NS_RelaxStrictFileOriginPolicy
331 bool allowsRelaxStrictFileOriginPolicy
(in nsIURI aURI
);
335 * Generates a Cache-Key for the Cors-Preflight Cache
338 ACString getPrefLightCacheKey
(in nsIURI aURI
,in bool aWithCredentials
,
339 in const_OriginAttributes aOriginAttributes
);
343 * Checks if the Principals URI has first party storage access
344 * when loaded inside the provided 3rd party resource window.
345 * See also: ContentBlocking::ShouldAllowAccessFor
347 bool hasFirstpartyStorageAccess
(in mozIDOMWindow aWindow
, out uint32_t rejectedReason
);
351 * Returns a Key for the LocalStorage Manager, used to
352 * check the Principals Origin Storage usage.
354 readonly attribute ACString localStorageQuotaKey
;
358 * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy
360 * The value returned by this method feeds into the the Secure Context
361 * algorithm that determins the value of Window.isSecureContext and
362 * WorkerGlobalScope.isSecureContext.
364 * This method returns false instead of throwing upon errors.
367 readonly attribute
boolean isOriginPotentiallyTrustworthy
;
370 * Returns the Flags of the Principals
371 * associated AboutModule, in case there is one.
373 uint32_t getAboutModuleFlags
();
376 * Returns the Key to access the Principals
377 * Origin Local/Session Storage
379 readonly attribute ACString storageOriginKey
;
382 * Creates and Returns a new ReferrerInfo with the
385 nsIReferrerInfo createReferrerInfo
(in ReferrerPolicy aReferrerPolicy
);
388 * The base part of |origin| without the concatenation with |originSuffix|.
389 * This doesn't have the important invariants described above with |origin|,
390 * and as such should only be used for legacy situations.
392 readonly attribute ACString originNoSuffix
;
395 * A string of the form !key1=value1&key2=value2, where each pair represents
396 * an attribute with a non-default value. If all attributes have default
397 * values, this is the empty string.
399 * The value of .originSuffix is automatically serialized into .origin, so any
400 * consumers using that are automatically origin-attribute-aware. Consumers with
401 * special requirements must inspect and compare .originSuffix manually.
403 readonly attribute AUTF8String originSuffix
;
406 * A canonical representation of the site-origin for this principal.
407 * This string has the same format as |origin| (see above). Two principals
408 * with differing |siteOrigin| values will never compare equal, even when
409 * considering domain mutations.
411 * For most principals, |siteOrigin| matches |origin| precisely. Only
412 * principals which allow mutating |domain|, such as ContentPrincipal,
413 * override the default implementation in BasePrincipal.
415 readonly attribute ACString siteOrigin
;
418 * The base part of |siteOrigin| without the concatenation with
421 readonly attribute ACString siteOriginNoSuffix
;
424 * The base domain of the principal URI to which this principal pertains
425 * (generally the document URI), handling null principals and
426 * non-hierarchical schemes correctly.
428 readonly attribute ACString baseDomain
;
431 * Gets the ID of the add-on this principal belongs to.
433 readonly attribute AString addonId
;
435 readonly attribute nsISupports addonPolicy
;
438 * Gets the id of the user context this principal is inside. If this
439 * principal is inside the default userContext, this returns
440 * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
442 [infallible
] readonly attribute
unsigned long userContextId
;
445 * Gets the id of the private browsing state of the context containing
446 * this principal. If the principal has a private browsing value of 0, it
447 * is not in private browsing.
449 [infallible
] readonly attribute
unsigned long privateBrowsingId
;
452 * Returns true iff the principal is inside an isolated mozbrowser element.
453 * <xul:browser> is not considered to be a mozbrowser element.
454 * <iframe mozbrowser noisolation> does not count as isolated since
455 * isolation is disabled. Isolation can only be disabled if the
456 * containing document is chrome.
458 [infallible
] readonly attribute
boolean isInIsolatedMozBrowserElement
;
461 * Returns true iff this is a null principal (corresponding to an
462 * unknown, hence assumed minimally privileged, security context).
464 [infallible
] readonly attribute
boolean isNullPrincipal
;
467 * Returns true iff this principal corresponds to a principal origin.
469 [infallible
] readonly attribute
boolean isContentPrincipal
;
472 * Returns true iff this is an expanded principal.
474 [infallible
] readonly attribute
boolean isExpandedPrincipal
;
477 * Returns true iff this is the system principal. C++ callers should use
478 * IsSystemPrincipal() instead of this scriptable accessor.
480 readonly attribute
boolean isSystemPrincipal
;
483 * Faster and nicer version callable from C++. Callers must include
484 * BasePrincipal.h, where it's implemented.
487 inline bool IsSystemPrincipal
() const;
491 * Returns true iff the principal is either an addon principal or
492 * an expanded principal, which contains at least one addon principal.
494 [infallible
] readonly attribute
boolean isAddonOrExpandedAddonPrincipal
;
498 friend std
::ostream
& operator
<<(std
::ostream
& aOut
, const nsIPrincipal
& aPrincipal
) {
499 nsIPrincipal
* principal
= const_cast
<nsIPrincipal
*>(&aPrincipal
);
500 nsAutoCString origin
;
501 mozilla
::DebugOnly
<nsresult
> rv
= principal
->GetOrigin
(origin
);
502 MOZ_ASSERT
(NS_SUCCEEDED
(rv
));
503 return aOut
<< "nsIPrincipal { " << origin
<< " }";
507 * Returns true if the URI is an Onion URI
509 [infallible
] readonly attribute
boolean isOnion
;
512 * Returns true if the Domain Policy allows js execution
513 * for the Principals URI
515 readonly attribute
boolean isScriptAllowedByPolicy
;
519 * Returns true if the Principal can acess l10n
520 * features for the Provided DocumentURI
522 boolean isL10nAllowed
(in nsIURI aDocumentURI
);
525 * Returns a nsIPrincipal, with one less Subdomain Segment
526 * Returns `nullptr` if there are no more segments to remove.
529 [infallible
] readonly attribute nsIPrincipal nextSubDomainPrincipal
;
532 * Returns if the principal is for an IP address.
534 [infallible
] readonly attribute
boolean isIpAddress
;
537 * Returns if the principal is for a local IP address.
539 [infallible
] readonly attribute
boolean isLocalIpAddress
;
544 * If SystemPrincipal is too risky to use, but we want a principal to access
545 * more than one origin, ExpandedPrincipals letting us define an array of
546 * principals it subsumes. So script with an ExpandedPrincipals will gain
547 * same origin access when at least one of its principals it contains gained
548 * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
549 * principal, and by another ExpandedPrincipal that has all its principals.
550 * It is added for jetpack content-scripts to let them interact with the
551 * content and a well defined set of other domains, without the risk of
552 * leaking out a system principal to the content. See: Bug 734891
554 [uuid(f3e177Df
-6a5e
-489f
-80a7
-2dd1481471d8
)]
555 interface nsIExpandedPrincipal
: nsISupports
558 * An array of principals that the expanded principal subsumes.
560 * When an expanded principal is used as a triggering principal for a
561 * request that inherits a security context, one of its constitutent
562 * principals is inherited rather than the expanded principal itself. The
563 * last principal in the allowlist is the default principal to inherit.
565 * Note: this list is not reference counted, it is shared, so
566 * should not be changed and should only be used ephemerally.
568 [noscript
, notxpcom
, nostdcall
]
569 PrincipalArray AllowList
();
573 * Bug 1548468: Move CSP off ExpandedPrincipal.
575 * A Content Security Policy associated with this principal. Use this function
576 * to query the associated CSP with this principal.
578 readonly attribute nsIContentSecurityPolicy csp
;
581 inline already_AddRefed
<nsIContentSecurityPolicy
> GetCsp
()
583 nsCOMPtr
<nsIContentSecurityPolicy
> result
;
584 mozilla
::DebugOnly
<nsresult
> rv
= GetCsp
(getter_AddRefs
(result
));
585 MOZ_ASSERT
(NS_SUCCEEDED
(rv
));
586 return result.forget
();