/* -*- 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" %} interface nsIURI; interface nsIContentSecurityPolicy; [ptr] native JSContext(JSContext); [ptr] native JSPrincipals(JSPrincipals); [ptr] native PrincipalArray(nsTArray >); [scriptable, builtinclass, uuid(86e5fd29-dccb-4547-8918-f224005479a0)] 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++ inline bool Equals(nsIPrincipal* aOther) { bool equal = false; return NS_SUCCEEDED(Equals(aOther, &equal)) && equal; } inline bool EqualsConsideringDomain(nsIPrincipal* aOther) { bool equal = false; return NS_SUCCEEDED(EqualsConsideringDomain(aOther, &equal)) && equal; } %} /** * 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); %{C++ inline bool Subsumes(nsIPrincipal* aOther) { bool subsumes = false; return NS_SUCCEEDED(Subsumes(aOther, &subsumes)) && subsumes; } inline bool SubsumesConsideringDomain(nsIPrincipal* aOther) { bool subsumes = false; return NS_SUCCEEDED(SubsumesConsideringDomain(aOther, &subsumes)) && subsumes; } %} /** * 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. */ [noscript] attribute nsIContentSecurityPolicy csp; /** * 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; /** * Returns the jar prefix of the principal. * The jar prefix is a string that can be used to isolate data or * permissions between different principals while taking into account * parameters like the app id or the fact that the principal is embedded in * a mozbrowser. * Some principals will return an empty string. * Some principals will assert if you try to access the jarPrefix. * * The jarPrefix is intended to be an opaque identifier. It is currently * "human-readable" but no callers should assume it will stay as is and * it might be crypto-hashed at some point. */ readonly attribute AUTF8String jarPrefix; /** * 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; /** * 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. * * originsuffix are intended to be a replacement for jarPrefix, which will * eventually be removed. */ readonly attribute AUTF8String originSuffix; /** * 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; const short APP_STATUS_NOT_INSTALLED = 0; const short APP_STATUS_INSTALLED = 1; const short APP_STATUS_PRIVILEGED = 2; const short APP_STATUS_CERTIFIED = 3; /** * Gets the principal's app status, which indicates whether the principal * corresponds to "app code", and if it does, how privileged that code is. * This method returns one of the APP_STATUS constants above. * * Note that a principal may have * * appId != nsIScriptSecurityManager::NO_APP_ID && * appId != nsIScriptSecurityManager::UNKNOWN_APP_ID * * and still have appStatus == APP_STATUS_NOT_INSTALLED. That's because * appId identifies the app that contains this principal, but a window * might be contained in an app and not be running code that the app has * vouched for. For example, the window might be inside an