/* -*- 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 JSContext; 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, uuid(3a283dc9-f733-4618-a36f-e2b68c280ab7)] 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 doesn't take document.domain changes into account. */ boolean equalsIgnoringDomain(in nsIPrincipal other); /** * Returns a hash value for the principal. */ [noscript] readonly attribute unsigned long hashValue; /** * The domain security policy of the principal. */ // XXXcaa should this be here? The script security manager is the only // thing that should care about this. Wouldn't storing this data in one // of the hashtables in nsScriptSecurityManager be better? // XXXbz why is this writable? Who should have write access to this? What // happens if this principal is in our hashtable and we pass it out of the // security manager and someone writes to this field? Especially if they // write garbage? If we need to give someone other than the security // manager a way to set this (which I question, since it can increase the // permissions of a page) it should be a |void clearSecurityPolicy()| // method. [noscript] attribute voidPtr securityPolicy; /** * 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 congruent with HTMLDocument.domain, and may be null. * Setting this has no effect on the URI. */ [noscript] attribute nsIURI domain; /** * The origin of this principal's codebase URI. * An origin is defined as: scheme + host + port. */ // XXXcaa this should probably be turned into an nsIURI. // The system principal's origin should be some caps namespace // with a chrome URI. All of chrome should probably be the same. readonly attribute string origin; /** * 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 for codebase principals * ignores changes to document.domain. */ boolean subsumesIgnoringDomain(in nsIPrincipal other); /** * 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 are not allowed to load anything. This is changed slightly * by the optional flag allowIfInheritsPrincipal (which defaults to false) * which allows the load of a data: URI (which inherits the principal of * its loader) or a URI with the same principal as its loader (eg. a * Blob URI). * In these cases, with allowIfInheritsPrincipal set to true, the URI can * be loaded by a null 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; /** * Returns the extended origin of the principal. * The extended origin is a string that has more information than the origin * and 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 the origin for extendedOrigin. * Some principals will assert if you try to access the extendedOrigin. * * The extendedOrigin 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 extendedOrigin; 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; /** * Shows the status of the app. * Can be: APP_STATUS_NOT_INSTALLED, APP_STATUS_INSTALLED, * APP_STATUS_PRIVILEGED or APP_STATUS_CERTIFIED. */ readonly attribute unsigned short appStatus; %{C++ uint16_t GetAppStatus() { uint16_t appStatus; nsresult rv = GetAppStatus(&appStatus); if (NS_FAILED(rv)) { return APP_STATUS_NOT_INSTALLED; } return appStatus; } %} /** * Returns the app id the principal is in, or returns * nsIScriptSecurityManager::NO_APP_ID if this principal isn't part of an * app. */ readonly attribute unsigned long appId; %{C++ uint32_t GetAppId() { uint32_t appId; mozilla::DebugOnly rv = GetAppId(&appId); MOZ_ASSERT(NS_SUCCEEDED(rv)); return appId; } %} /** * Returns true iif the principal is inside a browser element. */ readonly attribute boolean isInBrowserElement; %{C++ bool GetIsInBrowserElement() { bool isInBrowserElement; mozilla::DebugOnly rv = GetIsInBrowserElement(&isInBrowserElement); MOZ_ASSERT(NS_SUCCEEDED(rv)); return isInBrowserElement; } %} /** * Returns true if this principal has an unknown appId. This shouldn't * generally be used. We only expose it due to not providing the correct * appId everywhere where we construct principals. */ readonly attribute boolean unknownAppId; %{C++ bool GetUnknownAppId() { bool unkwnownAppId; mozilla::DebugOnly rv = GetUnknownAppId(&unkwnownAppId); MOZ_ASSERT(NS_SUCCEEDED(rv)); return unkwnownAppId; } %} /** * Returns true iff this principal is a null principal (corresponding to an * unknown, hence assumed minimally privileged, security context). */ readonly attribute boolean isNullPrincipal; }; /** * If nsSystemPrincipal is too risky to use, but we want a principal to access * more than one origin, nsExpandedPrincipals letting us define an array of * principals it subsumes. So script with an nsExpandedPrincipals will gain * same origin access when at least one of its principals it contains gained * sameorigin acccess. An nsExpandedPrincipal will be subsumed by the system * principal, and by another nsExpandedPrincipal that has all its principals. * It is added for jetpack content-scripts to let them interact with the * content and a well defined set of other domains, without the risk of * leaking out a system principal to the content. See: Bug 734891 */ [uuid(f3e177Df-6a5e-489f-80a7-2dd1481471d8)] interface nsIExpandedPrincipal : nsISupports { /** * An array of principals that the expanded principal subsumes. * Note: this list is not reference counted, it is shared, so * should not be changed and should only be used ephemerally. */ [noscript] readonly attribute PrincipalArray whiteList; };