/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ /* Defines the abstract interface for a principal. */ #include "nsISerializable.idl" %{C++ struct JSPrincipals; #include "nsCOMPtr.h" #include "nsTArray.h" #include "mozilla/DebugOnly.h" namespace mozilla { class OriginAttributes; } /** * Some methods have a fast path for the case when we're comparing a principal * to itself. The situation may happen for example with about:blank documents. */ #define DECL_FAST_INLINE_HELPER(method_) \ inline bool method_(nsIPrincipal* aOther) \ { \ mozilla::DebugOnly val = false; \ MOZ_ASSERT_IF(this == aOther, \ NS_SUCCEEDED(method_(aOther, &val)) && val); \ \ bool retVal = false; \ return \ this == aOther || \ (NS_SUCCEEDED(method_(aOther, &retVal)) && retVal); \ } %} interface nsIURI; interface nsIContentSecurityPolicy; webidl Document; [ptr] native JSContext(JSContext); [ptr] native JSPrincipals(JSPrincipals); [ref] native PrincipalArray(const nsTArray>); [ref] native const_OriginAttributes(const mozilla::OriginAttributes); [scriptable, builtinclass, uuid(f75f502d-79fd-48be-a079-e5a7b8f80c8b)] interface nsIPrincipal : nsISerializable { /** * Returns whether the other principal is equivalent to this principal. * Principals are considered equal if they are the same principal, or * they have the same origin. */ boolean equals(in nsIPrincipal other); /** * Like equals, but takes document.domain changes into account. */ boolean equalsConsideringDomain(in nsIPrincipal other); %{C++ DECL_FAST_INLINE_HELPER(Equals) DECL_FAST_INLINE_HELPER(EqualsConsideringDomain) %} /** * Returns a hash value for the principal. */ [noscript] readonly attribute unsigned long hashValue; /** * The codebase URI to which this principal pertains. This is * generally the document URI. */ readonly attribute nsIURI URI; /** * The domain URI to which this principal pertains. * This is null unless script successfully sets document.domain to our URI * or a superdomain of our URI. * Setting this has no effect on the URI. * See https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#Changing_origin */ [noscript] attribute nsIURI domain; /** * Returns whether the other principal is equal to or weaker than this * principal. Principals are equal if they are the same object or they * have the same origin. * * Thus a principal always subsumes itself. * * The system principal subsumes itself and all other principals. * * A null principal (corresponding to an unknown, hence assumed minimally * privileged, security context) is not equal to any other principal * (including other null principals), and therefore does not subsume * anything but itself. */ boolean subsumes(in nsIPrincipal other); /** * Same as the previous method, subsumes(), but takes document.domain into * account. */ boolean subsumesConsideringDomain(in nsIPrincipal other); /** * Same as the subsumesConsideringDomain(), but ignores the first party * domain in its originAttributes. */ boolean subsumesConsideringDomainIgnoringFPD(in nsIPrincipal other); %{C++ DECL_FAST_INLINE_HELPER(Subsumes) DECL_FAST_INLINE_HELPER(SubsumesConsideringDomain) DECL_FAST_INLINE_HELPER(SubsumesConsideringDomainIgnoringFPD) #undef DECL_FAST_INLINE_HELPER %} /** * Checks whether this principal is allowed to load the network resource * located at the given URI under the same-origin policy. This means that * codebase principals are only allowed to load resources from the same * domain, the system principal is allowed to load anything, and null * principals can only load URIs where they are the principal. This is * changed by the optional flag allowIfInheritsPrincipal (which defaults to * false) which allows URIs that inherit their loader's principal. * * If the load is allowed this function does nothing. If the load is not * allowed the function throws NS_ERROR_DOM_BAD_URI. * * NOTE: Other policies might override this, such as the Access-Control * specification. * NOTE: The 'domain' attribute has no effect on the behaviour of this * function. * * * @param uri The URI about to be loaded. * @param report If true, will report a warning to the console service * if the load is not allowed. * @param allowIfInheritsPrincipal If true, the load is allowed if the * loadee inherits the principal of the * loader. * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed. */ void checkMayLoad(in nsIURI uri, in boolean report, in boolean allowIfInheritsPrincipal); /** * A Content Security Policy associated with this principal. * Use this function to query the associated CSP with this principal. * Please *only* use this function to *set* a CSP when you know exactly what you are doing. * Most likely you want to call ensureCSP instead of setCSP. */ [noscript] attribute nsIContentSecurityPolicy csp; /* * Use this function to query a CSP associated with this principal. * If no CSP is associated with this principal then one is created * internally and setRequestContext is called on the CSP using aDocument. * * Please note if aDocument is null, then setRequestContext on the * CSP object is called using the current principal. */ [noscript] nsIContentSecurityPolicy ensureCSP(in Document aDocument); /** * A speculative Content Security Policy associated with this * principal. Set during speculative loading (preloading) and * used *only* for preloads. * * If you want to query the CSP associated with that principal, * then this is *not* what you want. Instead query 'csp'. */ [noscript] readonly attribute nsIContentSecurityPolicy preloadCsp; /* * Use this function to query a speculative CSP associated with this * principal. If no speculative CSP is associated with this principal * then one is created internally and setRequestContext is called on * the CSP using aDocument. * * Please note if aDocument is null, then setRequestContext on the * speculative CSP object is called using the current principal. */ [noscript] nsIContentSecurityPolicy ensurePreloadCSP(in Document aDocument); /** * The CSP of the principal in JSON notation. * Note, that the CSP itself is not exposed to JS, but script * should be able to obtain a JSON representation of the CSP. */ readonly attribute AString cspJSON; /** * A dictionary of the non-default origin attributes associated with this * nsIPrincipal. * * Attributes are tokens that are taken into account when determining whether * two principals are same-origin - if any attributes differ, the principals * are cross-origin, even if the scheme, host, and port are the same. * Attributes should also be considered for all security and bucketing decisions, * even those which make non-standard comparisons (like cookies, which ignore * scheme, or quotas, which ignore subdomains). * * If you're looking for an easy-to-use canonical stringification of the origin * attributes, see |originSuffix| below. */ [implicit_jscontext] readonly attribute jsval originAttributes; [noscript, notxpcom, nostdcall, binaryname(OriginAttributesRef)] const_OriginAttributes OriginAttributesRef(); /** * A canonical representation of the origin for this principal. This * consists of a base string (which, for codebase principals, is of the * format scheme://host:port), concatenated with |originAttributes| (see * below). * * We maintain the invariant that principalA.equals(principalB) if and only * if principalA.origin == principalB.origin. */ readonly attribute ACString origin; /** * The base part of |origin| without the concatenation with |originSuffix|. * This doesn't have the important invariants described above with |origin|, * and as such should only be used for legacy situations. */ readonly attribute ACString originNoSuffix; /** * A string of the form !key1=value1&key2=value2, where each pair represents * an attribute with a non-default value. If all attributes have default * values, this is the empty string. * * The value of .originSuffix is automatically serialized into .origin, so any * consumers using that are automatically origin-attribute-aware. Consumers with * special requirements must inspect and compare .originSuffix manually. */ readonly attribute AUTF8String originSuffix; /** * A canonical representation of the site-origin for this principal. * This string has the same format as |origin| (see above). Two principals * with differing |siteOrigin| values will never compare equal, even when * considering domain mutations. * * For most principals, |siteOrigin| matches |origin| precisely. Only * principals which allow mutating |domain|, such as ContentPrincipal, * override the default implementation in BasePrincipal. * * TODO(nika): Use this in DocGroup. */ readonly attribute ACString siteOrigin; /** * The base domain of the codebase URI to which this principal pertains * (generally the document URI), handling null principals and * non-hierarchical schemes correctly. */ readonly attribute ACString baseDomain; /** * Gets the id of the app this principal is inside. If this principal is * not inside an app, returns nsIScriptSecurityManager::NO_APP_ID. * * Note that this principal does not necessarily have the permissions of * the app identified by appId. For example, this principal might * correspond to an iframe whose origin differs from that of the app frame * containing it. In this case, the iframe will have the appId of its * containing app frame, but the iframe must not run with the app's * permissions. * * Similarly, this principal might correspond to an