pjs/caps/idl/nsIPrincipal.idl

/* -*- 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);

[uuid(a67c4736-9a95-4ce1-9ffc-3f88c0913a34)]
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
     * certificateID or the origin.  grantedList and deniedList are
     * space-separated lists of capabilities which were explicitly granted
     * or denied by a pref.
     */
    void getPreferences(out string prefBranch, out string id,
                        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 ID
     */
    boolean equals(in nsIPrincipal other);

    /**
     * Returns a hash value for the principal.
     */
    readonly attribute unsigned long hashValue;

    /**
     * Returns the JS equivalent of the principal.
     * @see JSPrincipals.h
     */
    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?
    attribute voidPtr securityPolicy;

    // XXXcaa probably should be turned into {get|set}CapabilityFlags
    short canEnableCapability(in string capability);
    void setCanEnableCapability(in string capability, in short canEnable);
    boolean isCapabilityEnabled(in string capability, in voidPtr annotation);
    void enableCapability(in string capability, inout voidPtr annotation);
    void revertCapability(in string capability, inout voidPtr annotation);
    void disableCapability(in string capability, inout voidPtr annotation);

    /**
     * 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.
     */
    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.
    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 string certificateID;

    /**
     * The common name for the certificate.
     * This pertains to the certificate authority organization.
     * Throws if there is no certificate associated with this principal.
     */
    attribute string commonName;

    /**
     * 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 subsumes itself if it is equal to itself.
     *
     * The system principal subsumes itself and all other principals except
     * the non-principal.
     *
     * The non-principal is not equal to itself or any other principal, and
     * therefore does not subsume 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.
     */
    boolean subsumes(in nsIPrincipal other);
};