Please note, this is a STATIC archive of website developer.mozilla.org from November 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
Your Search Results

    nsIPrincipal

    Provides the interface to a principal, which represents a security context. On the web, for example, a typical principal is comprised of an URL scheme, host, and port.
    Inherits from: nsISerializable Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

    For details on principals, how they work, and how to get the appropriate one, see Security check basics.

    Method overview

    short canEnableCapability(in string capability); Native code only!
    void checkMayLoad(in nsIURI uri, in boolean report);
    void disableCapability(in string capability, inout voidPtr annotation); Native code only!
    void enableCapability(in string capability, inout voidPtr annotation); Native code only!
    boolean equals(in nsIPrincipal other);
    JSPrincipals getJSPrincipals(in JSContext cx); Native code only!
    void getPreferences(out string prefBranch, out string id, out string subjectName, out string grantedList, out string deniedList, out boolean isTrusted);
    boolean isCapabilityEnabled(in string capability, in voidPtr annotation); Native code only!
    void revertCapability(in string capability, inout voidPtr annotation); Native code only!
    void setCanEnableCapability(in string capability, in short canEnable); Native code only!
    boolean subsumes(in nsIPrincipal other);

    Attributes

    Attribute Type Description
    certificate nsISupports The certificate associated with this principal, if any. If there isn't one, this will return null. Getting this attribute never throws. Read only.
    certificateID string The fingerprint ID of this principal's certificate. Throws if there is no certificate associated with this principal. Read only. Obsolete since Gecko 1.8
    commonName string The common name for the certificate. This pertains to the certificate authority organization. Throws if there is no certificate associated with this principal. Obsolete since Gecko 1.8
    csp nsIContentSecurityPolicy A Content Security Policy associated with this principal. Native code only!
    domain nsIURI 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. Native code only!
    fingerprint AUTF8String The fingerprint ID of this principal's certificate. Throws if there is no certificate associated with this principal. Read only.
    hasCertificate boolean Whether this principal is associated with a certificate. Read only.
    hashValue unsigned long Returns a hash value for the principal. Read only. Native code only!
    origin string The origin of this principal's codebase URI. An origin is defined as: scheme + host + port. Read only.
    prettyName AUTF8String

    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. Read only.
    securityPolicy voidPtr The domain security policy of the principal. Native code only!
    subjectName AUTF8String

    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. Read only.
    URI nsIURI

    The codebase URI to which this principal pertains. This is generally the document URI. Read only.

    Note: This wasn't accessible by scripts prior to Gecko 2.0.

    Constants

    Principal capability constants

    These values indicate the capabilities of a principal. The order is significant; if an operation is performed on a set of capabilities, the minimum is computed.

    Constant Value Description
    ENABLE_DENIED 1  
    ENABLE_UNKNOWN 2  
    ENABLE_WITH_USER_PERMISSION 3  
    ENABLE_GRANTED 4  

    Methods

    Native code only!

    canEnableCapability

    short canEnableCapability(
  in string capability
);
    Parameters
    capability
    Missing Description
    Return value

    Missing Description

    Exceptions thrown
    Missing Exception
    Missing Description

    Requires Gecko 1.9 (Firefox 3)

    checkMayLoad()

    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.

    Note: Prior to Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), this was not available to scripts.

    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.

    void checkMayLoad(
  in nsIURI uri,
  in boolean report
);
    Parameters
    uri
    Missing Description
    report
    If true, will report a warning to the console service if the load is not allowed.
    Exceptions thrown
    NS_ERROR_DOM_BAD_URI
    The load is not permitted.

    Native code only!

    disableCapability

    void disableCapability(
  in string capability,
  inout voidPtr annotation
);
    Parameters
    capability
    Missing Description
    annotation
    Missing Description

    Native code only!

    enableCapability

    void enableCapability(
  in string capability,
  inout voidPtr annotation
);
    Parameters
    capability
    Missing Description
    annotation
    Missing Description

    equals()

    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
);
    Parameters
    other
    The other principal to compare against.
    Return value

    true if the two principals are equivalent; otherwise false.

    Native code only!

    getJSPrincipals

    Returns the JS equivalent of the principal.

    JSPrincipals getJSPrincipals(
  in JSContext cx
);
    Parameters
    cx
    Missing Description
    Return value

    Missing Description

    getPreferences()

    Returns the security preferences associated with this principal.

    void getPreferences(
  out string prefBranch,
  out string id,
  out string subjectName,
  out string grantedList,
  out string deniedList,
  out boolean isTrusted
);
    Parameters
    prefBranch
    On return, contains the preference branch to which the preferences pertain.
    id
    A semi-unique ID relating to either the fingerprint or the origin.
    subjectName
    A name identifying the entity the principal represents; this may be an empty string.
    grantedList
    Space-delineated list of capabilities which are explicitly granted by a preference.
    deniedList
    Space-delineated list of capabilities which are explicitly denied by a preference.
    isTrusted
    true if the certificate is a codebase trusted one.

    Native code only!

    isCapabilityEnabled

    boolean isCapabilityEnabled(
  in string capability,
  in voidPtr annotation
);
    Parameters
    capability
    Missing Description
    annotation
    Missing Description
    Return value

    Missing Description

    Exceptions thrown
    Missing Exception
    Missing Description

    Native code only!

    revertCapability

    void revertCapability(
  in string capability,
  inout voidPtr annotation
);
    Parameters
    capability
    Missing Description
    annotation
    Missing Description
    Exceptions thrown
    Missing Exception
    Missing Description

    Native code only!

    setCanEnableCapability

    void setCanEnableCapability(
  in string capability,
  in short canEnable
);
    Parameters
    capability
    Missing Description
    canEnable
    Missing Description
    Exceptions thrown
    Missing Exception
    Missing Description

    Requires Gecko 1.8 (Firefox 1.5 / Thunderbird 1.5 / SeaMonkey 1.0)

    subsumes()

    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. A principal always subsumes itself.

    Note: Prior to Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1), this was not available to scripts.

    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.

    boolean subsumes(
  in nsIPrincipal other
);
    Parameters
    other
    Missing Description
    Return value

    true if this principal subsumes the specified principal; otherwise false.

    See also

    Document Tags and Contributors

     Contributors to this page: tomasz, Sheppy, paa, Nickolay
     Last updated by: tomasz,