/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ /* ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is mozilla.org code. * * The Initial Developer of the Original Code is * Netscape Communications Corporation. * Portions created by the Initial Developer are Copyright (C) 1999-2003 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Mitchell Stoltz * Christopher A. Aillon * * Alternatively, the contents of this file may be used under the terms of * either of the GNU General Public License Version 2 or later (the "GPL"), * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ /* Defines the abstract interface for a principal. */ #include "nsISerializable.idl" %{C++ struct JSContext; struct JSPrincipals; %} interface nsIURI; [ptr] native JSContext(JSContext); [ptr] native JSPrincipals(JSPrincipals); [scriptable, uuid(b8268b9a-2403-44ed-81e3-614075c92034)] interface nsIPrincipal : nsISerializable { /** * Values of capabilities for each principal. Order is * significant: if an operation is performed on a set * of capabilities, the minimum is computed. */ const short ENABLE_DENIED = 1; const short ENABLE_UNKNOWN = 2; const short ENABLE_WITH_USER_PERMISSION = 3; const short ENABLE_GRANTED = 4; /** * Returns the security preferences associated with this principal. * prefBranch will be set to the pref branch to which these preferences * pertain. id is a pseudo-unique identifier, pertaining to either the * fingerprint or the origin. subjectName is a name that identifies the * entity this principal represents (may be empty). grantedList and * deniedList are space-separated lists of capabilities which were * explicitly granted or denied by a pref. isTrusted is a boolean that * indicates whether this is a codebaseTrusted certificate. */ [noscript] void getPreferences(out string prefBranch, out string id, out string subjectName, out string grantedList, out string deniedList, out boolean isTrusted); /** * Returns whether the other principal is equivalent to this principal. * Principals are considered equal if they are the same principal, * they have the same origin, or have the same certificate fingerprint ID */ boolean equals(in nsIPrincipal other); /** * Returns a hash value for the principal. */ [noscript] readonly attribute unsigned long hashValue; /** * Returns the JS equivalent of the principal. * @see JSPrincipals.h */ [noscript] JSPrincipals getJSPrincipals(in JSContext cx); /** * 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; // XXXcaa probably should be turned into {get|set}CapabilityFlags // XXXbz again, what if this lives in our hashtable and someone // messes with it? Is that OK? [noscript] short canEnableCapability(in string capability); [noscript] void setCanEnableCapability(in string capability, in short canEnable); [noscript] boolean isCapabilityEnabled(in string capability, in voidPtr annotation); [noscript] void enableCapability(in string capability, inout voidPtr annotation); [noscript] void revertCapability(in string capability, inout voidPtr annotation); [noscript] void disableCapability(in string capability, inout voidPtr annotation); /** * The codebase URI to which this principal pertains. This is * generally the document URI. */ [noscript] 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. [noscript] readonly attribute string origin; /** * Whether this principal is associated with a certificate. */ readonly attribute boolean hasCertificate; /** * The fingerprint ID of this principal's certificate. * Throws if there is no certificate associated with this principal. */ // XXXcaa kaie says this may not be unique. We should probably // consider using something else for this.... readonly attribute AUTF8String fingerprint; /** * The pretty name for the certificate. This sort of (but not really) * identifies the subject of the certificate (the entity that stands behind * the certificate). Note that this may be empty; prefer to get the * certificate itself and get this information from it, since that may * provide more information. * * Throws if there is no certificate associated with this principal. */ readonly attribute AUTF8String prettyName; /** * Returns whether the other principal is equal to or weaker than this * principal. Principals are equal if they are the same object, they * have the same origin, or they have the same certificate ID. * * 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. * * Both codebase and certificate principals are subsumed by the system * principal, but no codebase or certificate principal yet subsumes any * other codebase or certificate principal. This may change in a future * release; note that nsIPrincipal is unfrozen, not slated to be frozen. * * XXXbz except see bug 147145! * * Note for the future: Perhaps we should consider a certificate principal * for a given URI subsuming a codebase principal for the same URI? Not * sure what the immediate benefit would be, but I think the setup could * make some code (e.g. MaybeDowngradeToCodebase) clearer. */ [noscript] boolean subsumes(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. * * 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. * @throws NS_ERROR_DOM_BAD_URI if the load is not allowed. */ [noscript] void checkMayLoad(in nsIURI uri, in boolean report); /** * The subject name for the certificate. This actually identifies the * subject of the certificate. This may well not be a string that would * mean much to a typical user on its own (e.g. it may have a number of * different names all concatenated together with some information on what * they mean in between). * * Throws if there is no certificate associated with this principal. */ readonly attribute AUTF8String subjectName; /** * The certificate associated with this principal, if any. If there isn't * one, this will return null. Getting this attribute never throws. */ readonly attribute nsISupports certificate; };