gecko-dev/caps/idl/nsIPrincipal.idl

221 lines
9.2 KiB
Plaintext

/* -*- 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 <mstoltz@netscape.com>
* Christopher A. Aillon <christopher@aillon.com>
*
* 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(fb9ddeb9-26f9-46b8-85d5-3978aaee05aa)]
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.
*/
[noscript] void getPreferences(out string prefBranch, out string id,
out string subjectName,
out string grantedList,
out string deniedList);
/**
* 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 domain, if non-null, or its
* codebase URI otherwise. 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);
/**
* 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;
};