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 webidl WebExtensionPolicy
;
49 [ptr] native JSContext
(JSContext
);
50 [ptr] native JSPrincipals
(JSPrincipals
);
51 [ref] native PrincipalArray
(const nsTArray
<nsCOMPtr
<nsIPrincipal
>>);
52 [ref] native const_OriginAttributes
(const mozilla
::OriginAttributes
);
53 native ReferrerPolicy
(mozilla
::dom
::ReferrerPolicy
);
55 [scriptable
, builtinclass
, uuid(f75f502d
-79fd
-48be
-a079
-e5a7b8f80c8b
)]
56 interface nsIPrincipal
: nsISupports
59 * Returns whether the other principal is equivalent to this principal.
60 * Principals are considered equal if they are the same principal, or
61 * they have the same origin.
63 boolean equals
(in nsIPrincipal other
);
66 * Returns whether the other principal is equivalent to this principal
67 * for permission purposes
68 * Matches {originAttributes ,equalsURIForPermission}
71 boolean equalsForPermission
(in nsIPrincipal other
, in bool aExactHost
);
74 * Like equals, but takes document.domain changes into account.
76 boolean equalsConsideringDomain
(in nsIPrincipal other
);
79 DECL_FAST_INLINE_HELPER
(Equals
)
80 DECL_FAST_INLINE_HELPER
(EqualsConsideringDomain
)
84 * Returns whether the Principals URI is equal to the other URI
86 boolean equalsURI
(in nsIURI aOtherURI
);
89 * Returns a hash value for the principal.
91 [notxpcom
, nostdcall
] readonly attribute
unsigned long hashValue
;
94 * The principal URI to which this principal pertains. This is
95 * generally the document URI.
97 [infallible
] readonly attribute nsIURI URI
;
100 * The domain URI to which this principal pertains.
101 * This is null unless script successfully sets document.domain to our URI
102 * or a superdomain of our URI.
103 * Setting this has no effect on the URI.
104 * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin
106 [noscript
] attribute nsIURI domain
;
109 * Returns whether the other principal is equal to or weaker than this
110 * principal. Principals are equal if they are the same object or they
111 * have the same origin.
113 * Thus a principal always subsumes itself.
115 * The system principal subsumes itself and all other principals.
117 * A null principal (corresponding to an unknown, hence assumed minimally
118 * privileged, security context) is not equal to any other principal
119 * (including other null principals), and therefore does not subsume
120 * anything but itself.
122 boolean subsumes
(in nsIPrincipal other
);
125 * Same as the previous method, subsumes(), but takes document.domain into
128 boolean subsumesConsideringDomain
(in nsIPrincipal other
);
131 * Same as the subsumesConsideringDomain(), but ignores the first party
132 * domain in its originAttributes.
134 boolean subsumesConsideringDomainIgnoringFPD
(in nsIPrincipal other
);
137 DECL_FAST_INLINE_HELPER
(Subsumes
)
138 DECL_FAST_INLINE_HELPER
(SubsumesConsideringDomain
)
139 DECL_FAST_INLINE_HELPER
(SubsumesConsideringDomainIgnoringFPD
)
140 #undef DECL_FAST_INLINE_HELPER
144 * Checks whether this principal is allowed to load the network resource
145 * located at the given URI under the same-origin policy. This means that
146 * content principals are only allowed to load resources from the same
147 * domain, the system principal is allowed to load anything, and null
148 * principals can only load URIs where they are the principal. This is
149 * changed by the optional flag allowIfInheritsPrincipal (which defaults to
150 * false) which allows URIs that inherit their loader's principal.
152 * If the load is allowed this function does nothing. If the load is not
153 * allowed the function throws NS_ERROR_DOM_BAD_URI.
155 * NOTE: Other policies might override this, such as the Access-Control
157 * NOTE: The 'domain' attribute has no effect on the behaviour of this
161 * @param uri The URI about to be loaded.
162 * @param allowIfInheritsPrincipal If true, the load is allowed if the
163 * loadee inherits the principal of the
165 * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed.
167 void checkMayLoad
(in nsIURI uri
,
168 in boolean allowIfInheritsPrincipal
);
171 * Like checkMayLoad, but if returning an error will also report that error
172 * to the console, using the provided window id. The window id may be 0 to
173 * report to just the browser console, not web consoles.
175 void checkMayLoadWithReporting
(in nsIURI uri
,
176 in boolean allowIfInheritsPrincipal
,
177 in unsigned long long innerWindowID
);
180 * Checks if the provided URI is considered third-party to the
181 * URI of the principal.
182 * Returns true if the URI is third-party.
184 * @param uri - The URI to check
186 boolean isThirdPartyURI
(in nsIURI uri
);
189 * Checks if the provided principal is considered third-party to the
190 * URI of the Principal.
191 * Returns true if the principal is third-party.
193 * @param principal - The principal to check
195 boolean isThirdPartyPrincipal
(in nsIPrincipal principal
);
198 * Checks if the provided channel is considered third-party to the
199 * URI of the principal.
200 * Returns true if the channel is third-party.
201 * Returns false if the Principal is a System Principal
203 * @param channel - The Channel to check
205 boolean isThirdPartyChannel
(in nsIChannel channel
);
208 * A dictionary of the non-default origin attributes associated with this
211 * Attributes are tokens that are taken into account when determining whether
212 * two principals are same-origin - if any attributes differ, the principals
213 * are cross-origin, even if the scheme, host, and port are the same.
214 * Attributes should also be considered for all security and bucketing decisions,
215 * even those which make non-standard comparisons (like cookies, which ignore
216 * scheme, or quotas, which ignore subdomains).
218 * If you're looking for an easy-to-use canonical stringification of the origin
219 * attributes, see |originSuffix| below.
222 readonly attribute jsval originAttributes
;
224 [noscript
, notxpcom
, nostdcall
, binaryname
(OriginAttributesRef
)]
225 const_OriginAttributes OriginAttributesRef
();
228 * A canonical representation of the origin for this principal. This
229 * consists of a base string (which, for content principals, is of the
230 * format scheme://host:port), concatenated with |originAttributes| (see
233 * We maintain the invariant that principalA.equals(principalB) if and only
234 * if principalA.origin == principalB.origin.
236 readonly attribute ACString origin
;
239 * Returns an ASCII compatible representation
240 * of the principals Origin
242 [noscript
] readonly attribute ACString asciiOrigin
;
245 * Returns the "host:port" portion of the
246 * Principals URI, if any.
248 readonly attribute ACString hostPort
;
251 * Returns the "host:port" portion of the
252 * Principals URI, if any.
254 readonly attribute ACString asciiHost
;
257 * Returns the "host" portion of the
258 * Principals URI, if any.
260 readonly attribute ACString host
;
263 * Returns the prePath of the principals uri
264 * follows the format scheme:
265 * "scheme://username:password@hostname:portnumber/"
267 readonly attribute ACString prePath
;
270 * Returns the filePath of the principals uri. See nsIURI.
272 readonly attribute ACString filePath
;
275 * Returns the ASCII Spec from the Principals URI.
276 * Might return the empty string, e.g. for the case of
277 * a SystemPrincipal or an EpxandedPrincipal.
279 * WARNING: DO NOT USE FOR SECURITY CHECKS.
280 * just for logging purposes!
282 readonly attribute ACString asciiSpec
;
285 * Returns the Spec from the Principals URI.
286 * Might return the empty string, e.g. for the case of
287 * a SystemPrincipal or an EpxandedPrincipal.
289 * WARNING: Do not land new Code using, as this will be removed soon
291 readonly attribute ACString spec
;
293 /* Returns the Pre Path of the Principals URI with
294 * user:pass stripped for privacy and spoof prevention
296 readonly attribute ACString exposablePrePath
;
298 /* Returns the Spec of the Principals URI with
299 * user/pass/ref/query stripped for privacy and spoof prevention
301 readonly attribute ACString exposableSpec
;
304 * Return the scheme of the principals URI
306 readonly attribute ACString scheme
;
309 * Checks if the Principal's URI Scheme matches with the parameter
311 * @param scheme The scheme to be checked
314 boolean schemeIs
(in string scheme
);
317 * Checks if the Principal's URI is contained in the given Pref
318 * @param pref The pref to be checked
321 boolean isURIInPrefList
(in string pref
);
324 * Uses NS_Security Compare to determine if the
325 * other URI is same-origin as the uri of the Principal
327 bool isSameOrigin
(in nsIURI otherURI
, in bool aIsPrivateWin
);
330 * Checks if the Principal is allowed to load the Provided file:// URI
331 * using NS_RelaxStrictFileOriginPolicy
333 bool allowsRelaxStrictFileOriginPolicy
(in nsIURI aURI
);
337 * Generates a Cache-Key for the Cors-Preflight Cache
340 ACString getPrefLightCacheKey
(in nsIURI aURI
,in bool aWithCredentials
,
341 in const_OriginAttributes aOriginAttributes
);
345 * Checks if the Principals URI has first party storage access
346 * when loaded inside the provided 3rd party resource window.
347 * See also: ContentBlocking::ShouldAllowAccessFor
349 bool hasFirstpartyStorageAccess
(in mozIDOMWindow aWindow
, out uint32_t rejectedReason
);
353 * Returns a Key for the LocalStorage Manager, used to
354 * check the Principals Origin Storage usage.
356 readonly attribute ACString localStorageQuotaKey
;
360 * https://w3c.github.io/webappsec-secure-contexts/#is-origin-trustworthy
362 * The value returned by this method feeds into the the Secure Context
363 * algorithm that determins the value of Window.isSecureContext and
364 * WorkerGlobalScope.isSecureContext.
366 * This method returns false instead of throwing upon errors.
369 readonly attribute
boolean isOriginPotentiallyTrustworthy
;
372 * Returns the Flags of the Principals
373 * associated AboutModule, in case there is one.
375 uint32_t getAboutModuleFlags
();
378 * Returns the Key to access the Principals
379 * Origin Local/Session Storage
381 readonly attribute ACString storageOriginKey
;
384 * Creates and Returns a new ReferrerInfo with the
387 nsIReferrerInfo createReferrerInfo
(in ReferrerPolicy aReferrerPolicy
);
390 * The base part of |origin| without the concatenation with |originSuffix|.
391 * This doesn't have the important invariants described above with |origin|,
392 * and as such should only be used for legacy situations.
394 readonly attribute ACString originNoSuffix
;
397 * A string of the form ^key1=value1&key2=value2, where each pair represents
398 * an attribute with a non-default value. If all attributes have default
399 * values, this is the empty string.
401 * The value of .originSuffix is automatically serialized into .origin, so any
402 * consumers using that are automatically origin-attribute-aware. Consumers with
403 * special requirements must inspect and compare .originSuffix manually.
405 readonly attribute AUTF8String originSuffix
;
408 * A canonical representation of the site-origin for this principal.
409 * This string has the same format as |origin| (see above). Two principals
410 * with differing |siteOrigin| values will never compare equal, even when
411 * considering domain mutations.
413 * For most principals, |siteOrigin| matches |origin| precisely. Only
414 * principals which allow mutating |domain|, such as ContentPrincipal,
415 * override the default implementation in BasePrincipal.
417 readonly attribute ACString siteOrigin
;
420 * The base part of |siteOrigin| without the concatenation with
423 readonly attribute ACString siteOriginNoSuffix
;
426 * The base domain of the principal URI to which this principal pertains
427 * (generally the document URI), handling null principals and
428 * non-hierarchical schemes correctly.
430 readonly attribute ACString baseDomain
;
433 * Gets the ID of the add-on this principal belongs to.
435 readonly attribute AString addonId
;
437 readonly attribute WebExtensionPolicy addonPolicy
;
440 * Gets the id of the user context this principal is inside. If this
441 * principal is inside the default userContext, this returns
442 * nsIScriptSecurityManager::DEFAULT_USER_CONTEXT_ID.
444 [infallible
] readonly attribute
unsigned long userContextId
;
447 * Gets the id of the private browsing state of the context containing
448 * this principal. If the principal has a private browsing value of 0, it
449 * is not in private browsing.
451 [infallible
] readonly attribute
unsigned long privateBrowsingId
;
454 * Returns true iff the principal is inside an isolated mozbrowser element.
455 * <xul:browser> is not considered to be a mozbrowser element.
456 * <iframe mozbrowser noisolation> does not count as isolated since
457 * isolation is disabled. Isolation can only be disabled if the
458 * containing document is chrome.
460 [infallible
] readonly attribute
boolean isInIsolatedMozBrowserElement
;
463 * Returns true iff this is a null principal (corresponding to an
464 * unknown, hence assumed minimally privileged, security context).
466 [infallible
] readonly attribute
boolean isNullPrincipal
;
469 * Returns true iff this principal corresponds to a principal origin.
471 [infallible
] readonly attribute
boolean isContentPrincipal
;
474 * Returns true iff this is an expanded principal.
476 [infallible
] readonly attribute
boolean isExpandedPrincipal
;
479 * Returns true iff this is the system principal. C++ callers should use
480 * IsSystemPrincipal() instead of this scriptable accessor.
482 readonly attribute
boolean isSystemPrincipal
;
485 * Faster and nicer version callable from C++. Callers must include
486 * BasePrincipal.h, where it's implemented.
489 inline bool IsSystemPrincipal
() const;
493 * Returns true iff the principal is either an addon principal or
494 * an expanded principal, which contains at least one addon principal.
496 [infallible
] readonly attribute
boolean isAddonOrExpandedAddonPrincipal
;
500 friend std
::ostream
& operator
<<(std
::ostream
& aOut
, const nsIPrincipal
& aPrincipal
) {
501 nsIPrincipal
* principal
= const_cast
<nsIPrincipal
*>(&aPrincipal
);
502 nsAutoCString origin
;
503 mozilla
::DebugOnly
<nsresult
> rv
= principal
->GetOrigin
(origin
);
504 MOZ_ASSERT
(NS_SUCCEEDED
(rv
));
505 return aOut
<< "nsIPrincipal { " << origin
<< " }";
509 * Returns true if the URI is an Onion URI
511 [infallible
] readonly attribute
boolean isOnion
;
514 * Returns true if the Domain Policy allows js execution
515 * for the Principals URI
517 readonly attribute
boolean isScriptAllowedByPolicy
;
521 * Returns true if the Principal can acess l10n
522 * features for the Provided DocumentURI
524 boolean isL10nAllowed
(in nsIURI aDocumentURI
);
527 * Returns a nsIPrincipal, with one less Subdomain Segment
528 * Returns `nullptr` if there are no more segments to remove.
531 [infallible
] readonly attribute nsIPrincipal nextSubDomainPrincipal
;
534 * Returns if the principal is for an IP address.
536 [infallible
] readonly attribute
boolean isIpAddress
;
539 * Returns if the principal is for a local IP address.
541 [infallible
] readonly attribute
boolean isLocalIpAddress
;
544 * If this principal is a null principal, reconstruct the precursor
545 * principal which this null principal was derived from. This may be null,
546 * in which case this is not a null principal, there is no known precursor
547 * to this null principal, it was created by a privileged context, or there
548 * was a bugged origin in the precursor string.
550 * WARNING: Be careful when using this principal, as it is not part of the
551 * security properties of the null principal, and should NOT be used to
552 * grant a resource with a null principal access to resources from its
553 * precursor origin. This is only to be used for places where tracking how
554 * null principals were created is necessary.
556 [infallible
] readonly attribute nsIPrincipal precursorPrincipal
;
560 * If SystemPrincipal is too risky to use, but we want a principal to access
561 * more than one origin, ExpandedPrincipals letting us define an array of
562 * principals it subsumes. So script with an ExpandedPrincipals will gain
563 * same origin access when at least one of its principals it contains gained
564 * sameorigin acccess. An ExpandedPrincipal will be subsumed by the system
565 * principal, and by another ExpandedPrincipal that has all its principals.
566 * It is added for jetpack content-scripts to let them interact with the
567 * content and a well defined set of other domains, without the risk of
568 * leaking out a system principal to the content. See: Bug 734891
570 [uuid(f3e177Df
-6a5e
-489f
-80a7
-2dd1481471d8
)]
571 interface nsIExpandedPrincipal
: nsISupports
574 * An array of principals that the expanded principal subsumes.
576 * When an expanded principal is used as a triggering principal for a
577 * request that inherits a security context, one of its constitutent
578 * principals is inherited rather than the expanded principal itself. The
579 * last principal in the allowlist is the default principal to inherit.
581 * Note: this list is not reference counted, it is shared, so
582 * should not be changed and should only be used ephemerally.
584 [noscript
, notxpcom
, nostdcall
]
585 PrincipalArray AllowList
();
589 * Bug 1548468: Move CSP off ExpandedPrincipal.
591 * A Content Security Policy associated with this principal. Use this function
592 * to query the associated CSP with this principal.
594 readonly attribute nsIContentSecurityPolicy csp
;
597 inline already_AddRefed
<nsIContentSecurityPolicy
> GetCsp
()
599 nsCOMPtr
<nsIContentSecurityPolicy
> result
;
600 mozilla
::DebugOnly
<nsresult
> rv
= GetCsp
(getter_AddRefs
(result
));
601 MOZ_ASSERT
(NS_SUCCEEDED
(rv
));
602 return result.forget
();